Índice

Objetivo

Orientar os Squads 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, sendo: Conceitos, Configurações, Controle de Dados Protegidos, Integrações, Menu do Módulo e Pontos de Entrada.

Outras sub-pastas podem ser criadas pelas Squadspelos squads, quando necessário. Recomenda-se agrupar os assuntos por em sub-pastas, a fim de reduzir o número das mesmas e organizar da melhor maneira as documentaçõ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)

Image Added

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. 

Documento Técnico (Inovação)

     Sigla do Documento + Descrição da Story

     Ex.: DT Geração 1350, 1360 e 1370 Sped Fiscal TAF

            DT Geração 1350, 1360 e 1370 Sped Fiscal TAF versão 11.80

            DT Geração 1350, 1360 e 1370 Sped Fiscal TAF ARG

     Obs.: Quando o DT for elaborado para uma funcionalidade já existente, onde apenas houver atualização de versão ou para réplicas do produto, deve ser acrescentada a           versão ao final da nomenclatura do documento. Quando o projeto tratar de uma localização, deve ser incluída a sigla do país.

Documento Técnico (Manutenção)

     Ticket + ID da Issue + Sigla do Documento + Descrição da Issue

     Ex.: 122828 MRH-631 DT Erro Integração SAP (Issue Externa)

            122828 MRH-631 DT Erro Integração SAP ARG (Issue Externa)

            MRH-631 DT Erro Integração SAP (Issue Interna)

            MRH-631 DT Erro Integração SAP (Issue Interna)

            MRH-631 DT Erro Integração SAP ARG (Issue Interna)

Documento de Referência

     Nome da Tela + Código do Programa

     Ex.: Cadastro Produto MATA010

            Cadastro Produto MATA010 ARG

     Obs.: Quando o projeto tratar de uma localização deve ser incluído a sigla do país. 

Vídeo How To

     HOW TO + Segmento + Assunto + Parte 0x (opcional)

     Ex.: HOW TO - Manufatura - Geração 1350, 1360 e 1370 Sped Fiscal TAF

            HOW TO - Manufatura - Geração 1350, 1360 e 1370 Sped Fiscal TAF - Parte 1 (caso tenha mais de uma parte)

• No canto superior direito da página que se quer movimentar, clique em ...
• Após, clique em Mover.

Image Added

• Clique em Procurar e escolha a nova Página Pai.

Image Added

• A Página Pai é a página do módulo em: Documento de Referência/ Protheus 12/ MÓDULO

• Após, clique em Mover.

Image Added

Boas práticas

1. Observe se a estrutura da página onde se encontra o documento está correta e publicada.
2. Recomenda-se, fortemente, a estrutura das páginas divididas por assuntos comuns. Isto facilita a organização e localização das informações.
3. O nome das sub-pastas e páginas deve obedecer o padrão de nomenclatura corporativo.
4. Utilize tags adequadas para ajudar na localização dos assuntos.
5. Os modelos de documentação podem estar diferentes, pois muitas documentações são antigas. Neste caso, não há necessidade de refazer a documentação para adequar o modelo.
6. Revisite as documentações, pelo menos, as mais importantes e mais acessadas pelos clientes. Avalie se o conteúdo está correto. Caso seja necessário atualizá-lo, então recomenda-se refazer a documentação no novo modelo.
7. Atenção especial para os links internos que fazem referência a documentações que não existem mais.

Conclusão

 As páginas do período entre 2012 e 2016 devem ser verificadas e, mantidas, apenas as páginas válidas.

 As páginas posteriores a 2016 não precisam ser verificadas, neste momento.

 Todas as páginas válidas devem ser movidas para a pasta do Documento de Referência do módulo.

Mais informações

• Consulte a página da Documentação Protheus
• Conheça a Política da Qualidade da Documentação Protheus

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.