Índice

Objetivo

Orientar os Squads sobre o saneamento do TDN, na Base de conhecimento, restrito às páginas entre 2012 e 2016.

Introdução

O  padrão de qualidade de uma documentação não se limita apenas aos cuidados com o conteúdo, mas também, com a formatação das páginas utilizadas para a sua construção.

Neste sentido, a documentação para os sistemas TOTVS compreendem um padrão corporativo e, de acordo com este padrão, os documentos devem ser desenvolvidos para que a experiência do cliente seja a mais positiva possível. 

Espera-se que a documentação disponibilizada para os clientes internos e externos sejam claras, objetivas, seguindo o padrão de qualidade que representa a empresa e, principalmente, que agreguem conteúdo ao produto.

Com o objetivo de melhorar o auto-atendimento de busca das informações no TDN, faz-se necessário o saneamento das páginas antigas e desatualizadas,  pois muitas vezes geram dúvidas e causam situações de erro para os clientes do Protheus.

Procedimentos

Para realizar o saneamento, as páginas válidas devem ser movidas para a pasta de Documento de Referência do módulo, que contém toda a documentação perene sobre o módulo.

Na pasta de Documento de Referência do módulo, há sub-pastas comuns e, outras, que são específicas para cada módulo.

As sub-pastas comuns já foram criadas pela Engenharia Protheus e são: Conceitos, Configurações, Controle de Dados Protegidos, Integrações, Menu do Módulo e Pontos de Entrada.

Outras sub-pastas podem ser criadas pelas Squads, quando necessário. Recomenda-se agrupar os assuntos por sub-pastas, a fim de reduzir o número das mesmas e organizar da melhor maneira as documentações. 

Além dos assuntos, as documentações também podem ser diferenciadas quanto ao acesso, interno ou externo. Para isto, basta utilizar o recurso de Restrições.

As sub-pastas que forem criadas devem seguir a seguinte regra de nomenclatura: Descrição - Nome do módulo - P12

Observação: Caso um conteúdo esteja todo contido em uma página, não há necessidade de criar uma sub-pasta para o mesmo. 

Exemplo:

Documento de Referência

Protheus 12

Call Center - Protheus 12

Conceitos - Call Center - P12

Configurações - Call Center - P12

Controle de Dados Protegidos - Call Center - P12

Integrações - Call Center - P12

Menu do Módulo - Call Center - P12

Pontos de Entrada - Call Center - P12

Artigos - Call Center - P12  (ex. sub-pasta criada pela Squad, movida da Base de Conhecimento)

Cálculos - Call Center - P12  (ex. sub-pasta criada pela Squad, movida da Base de Conhecimento)

Legislações - Call Center - P12 (ex. sub-pasta criada pela Squad, movida da Base de Conhecimento)

FAQs - Call Center - P12 (ex. sub-pasta criada pela Squad, movida da Base de Conhecimento)

Opção Mover

É possível mover uma página ou uma pasta.  

Boas práticas

Estrutura da página

1. Observe se a estrutura da página onde se encontra o documento está correta, desde as principais (Documento de Referência e Novidades do Release) até o último nível da Página Agrupadora.
2. Verifique se a(s) página(s) agrupadora(s) está(ão) publicada(s).
3.  Certifique-se que o modelo escolhido é o mais adequado para o tipo de informação que se deseja publicar.

Nomenclatura

1. O nome da página deve obedecer o padrão de nomenclatura.
2. Lembre-se que o TDN não permite nomes repetidos para páginas.
3. Além de obedecer o padrão de nomenclatura, este nome deve remeter ao assunto, porém sem ser extenso.
4. Também é importante informar o país, quando se tratar de localização. 

Formatação

1. É importantíssimo manter a formatação padrão do documento, isto é: fontes, cores, título, tabelas etc.
2. O modelo informa quais são os campos obrigatórios e opcionais. Caso os campos opcionais não sejam utilizados, eles devem ser eliminados, isto é, não devem constar do documento.
3. Lembre-se que o documento é público para todos, então manter a formatação é muito importante, pois identifica o tipo de informação que a empresa está disponibilizando.
4. Para destacar os nomes das rotinas, campos, parâmetros, tabelas ou alguns termos importantes do texto, use o negrito.
5. Uma palavra ou expressão estrangeira deve ser substituída por uma forma equivalente em Português. Caso não seja possível a tradução, deve-se destacar a palavra estrangeira em itálico.
6. Ao utilizar imagens, certifique-se que ela esteja bem nítida.
7. Nos templates, os textos em azul e itálico são apenas de orientação para o preenchimento do documento e, por isso, não devem constar do mesmo.
8. Recursos como tabelas, caixas de texto para destacar alguma informação também são válidas.
9. A utilização de bullets (tópicos) é ideal para a numeração e organização da informação que se deseja transmitir.
10. As informações são localizadas no TDN, por meio das tags/labels que são termos chaves utilizados no mecanismo de busca da Central de Ajuda.

Conteúdo

1. O conteúdo do documento deve estar de acordo com o que o modelo utilizado. 
2. Podem ser utilizados imagens, links ou, até mesmo, vídeos para agregar mais informação.
3. Prints de tela do sistema também facilitam o entendimento. Porém, deve-se atentar que em alguns casos, as telas são alteradas (dependendo do release), sendo necessário também o ajuste na documentação.
4. Os exemplos são recursos interessantes e que ajudam muito na explicação das rotinas. Muitas vezes, um bom exemplo é mais válido que um texto extenso.
5. É importante destacar as informações relevantes e chamar a atenção do usuário para aquele conteúdo utilizando quadros, bordas ou cores diferentes.
6. Caso haja alguma alteração pontual significativa e com muitos passos, pode-se criar um vídeo (How To) e incluí-lo no documento.

Linguagem

1. O texto deve ser simples, claro e objetivo, além de obedecer as regras gramaticais da língua portuguesa.

2. A repetição de palavras/termos deve ser evitada. A  recomendação é para o o uso de frases curtas, pois as longas podem confundir o leitor e prejudicar o entendimento do texto, por torná-lo cansativo.

3. Verifique a pontuação, pois um texto mal pontuado tem muitas chances de conter ambiguidades.

4. As comparações com elementos concretos tornam o texto mais compreensível, portanto o uso de exemplos é muito bem vindo.

5. Recomenda-se cuidado com abreviaturas e siglas.

6. Coloque-se no lugar do leitor e observe se a informação é suficiente para o assunto abordado.

Conclusão

• Assunto: Todo texto é uma resposta às perguntas: "O que", "Como", "Quando", "Onde" e "Por que".
• Objetivo: Conheça o objetivo com clareza.
• Compreensão: Identifique os interesses e necessidades do leitor.
• Antecipação: Procure antecipar e responder às possíveis dúvidas que poderão ocorrer.
• Estruturação: Defina como o assunto será tratado e obedeça uma ordem ao conteúdo a partir de itens que facilitem a divisão geral dos assuntos.
• Linguagem: Use a linguagem adequada ao assunto, ao interlocutor e ao tipo de texto que está sendo produzido. Cuide para que não haja erros linguísticos e faça uma revisão.
• Padronização: Respeite o modelo adotado pela companhia, bem com a formatação definida para este modelo.

Mais informações

• Consulte o link para saber mais sobre Busca Unificada e Novo F1 do Produto 
• Para mais informações consulte o Estrutura e Templates do TDN.
• Conheça a nova área de Processos do TDN
• Consulte a Política da Qualidade da Documentação Protheus.