Padronização de Documentação – HELP

• Para poder realizar testes referente à rotina que será documentada, é necessário que tenha uma base local online, para que possam ser feitos testes e entender como funciona a rotina.
• Caso já exista alguma documentação antiga sobre a rotina que será documentada, a mesma deverá ser revisada, a fim de evitar erros ortográficos e verificar se a rotina ainda funciona da forma que está descrita nesta documentação. Alguns processos podem ser modificados pois há correções de erro e customizações no sistema, o que pode acarretar em mudanças em alguma rotina.
• A documentação SEMPRE deverá ser criada primeiramente no QualHelp. Assim que homologada, a mesma será migrada para o Help Oficial, e então, ficará disponível para os clientes.

Caso ainda não exista nenhuma documentação sobre a rotina, pode-se realizar os seguintes procedimentos:

• Verificar se existem chamados abertos sobre a funcionalidade em questão e avaliar se as informações que nele existem, são consistentes e verdadeiras e as informações poderiam fazer parte da documentação.
• Sempre que possível fazer levantamento das maiores dúvidas de cada módulo para então documentar. Este procedimento pode ser realizado mesmo que já exista uma documentação sobre a rotina.
• Conversar com pessoas que entendem da rotina, levantar as informações necessárias, fazer um estudo e então começar a estruturar a documentação e passar as informações para o QualHelp.
  

• Atenção redobrada em relação a ortografia! Isso envolve: erros de português, redundância nas frases, pleonasmo, gerundismo, falta de concordância, falta de pontuação ou pontuação incorreta. Dica: Utilizar o LibreOffice para realizar correções de ortografia.
• A linguagem na documentação deve ser clara e objetiva, contudo, rica em detalhes. A ideia é fazer com que o usuário entenda a explicação e já possa realizar o procedimento desejado sem dificuldade.
• Espaçamento entre os textos e as imagens das telas.
• Quando explicado um campo de uma tela, em campos obrigatórios usar o verbo que indica que ele é obrigado a preencher o mesmo, por exemplo o “deve-se”, “é necessário”. E quando forem campos opcionais simplesmente indicar que é opcional e ele pode ou não preencher, como o “pode-se”.
• Espaçamento entre os textos: quando apresentado os campos de uma tela, a frase introdutória deve ser separada dos itens por um enter e uso de duas barras invertidas “\\”, pois o Dokuwiki utiliza para pular uma linha, exemplo de estrutura na imagem abaixo.
• Títulos e subtítulos: no Dokuwiki é utilizado o sinal “=” para definir os tamanhos dos títulos e subtítulos. Em nossa documentação, os títulos e subtítulos devem ser utilizados da seguinte forma:
  • Título: deve ser utilizado 6 vezes o sinal “=”. No caso: ====== Título ======
  • Subtítulo: deve ser utilizado 4 vezes o sinal “=”. No caso: ==== Subtítulo ==== (neste caso, deve-se inserir 4 vezes o sinal “-”, abaixo do subtítulo, para que seja inserida uma linha. No caso: - - - -
  • Subtítulos em Documentações de rotina: deve ser utilizado 5 vezes o sinal “=”. No caso: ===== Subtítulo ===== (neste caso, deve-se inserir 4 vezes o sinal “-”, abaixo do subtítulo, para que seja inserida uma linha. No caso: - - - -

• Padronizar o uso de plurais nos textos, como exemplo o(s) e-mail(s), pois pode ser um e-mail ou vários e-mails.
• Quando a documentação estiver no processo de ser estruturada e documentada, no título deverá ter a frase Em construção , para que qualquer pessoa que for acessar, saiba que esta documentação não está 100% concluída. Esta informação só deve ser retirada quando a documentação for homologada e comprovada que todas as informações estão de acordo conforme a funcionalidade. Para exemplo:
  

• Evitar utilizar o termo “Clique aqui” para direcionar o usuário a outra documentação. O Google faz o direcionamento das documentações, portanto, é necessário informar o nome da rotina, ou o título da documentação para que o Google possa redirecionar o usuário ao link certo. O Google não redirecionará nada com o termo “Clique aqui.” Veja o exemplo abaixo:
  

• Não utilizar verbos no presente do subjuntivo, exemplo: Temos, alteramos, fazemos, apresentamos. Utilizar: tem de se, altera-se, deve-se, apresenta-se. Buscar sinônimos das palavras para não utilizar sempre o mesmo verbo, como deve-se pode ser substituído por: em que se, tem de se, é obrigatório, é recomendado, é preciso, é necessário…
• Ao detalhar campos e filtros, deve-se destacar o nome do filtro com negrito, e ao lado, informar a utilidade do mesmo, conforme mostra a imagem abaixo:
  

• Incluir exemplos de situações em algumas rotinas. Exemplos que utilizam como base a realidade do cliente, permite que o mesmo compreenda a funcionalidade de uma forma simples e didática. Veja o exemplo abaixo:
  

• Não utilizar o termo “flag”, pois não são todos os clientes que entendem seu significado. O termo correto a ser utilizado é “parâmetro”.

Após realizar o levantamento das informações a respeito das rotinas, deve-se analisá-las e separá-las por procedimentos, conforme segue abaixo:

1. Título.
2. Introdução: O que é a rotina, e/ou para que serve a rotina que está sendo documentada.
3. Caminho para acessar a rotina (Módulo > Menu > Opção de menu).
4. Breve apresentação da tela inicial da rotina com a imagem da tela inicial.

Exemplo:

5. Subtítulo. Abaixo, informar que para saber mais a respeito das funções ou dos filtros disponíveis de uma determinada rotina, deve-se clicar nas abas abaixo.
6. Criar os tópicos expansíveis com cada aba, função ou até mesmo, com os filtros ou campos da rotina:

Para criar os tópicos expansíveis, insira estas informações:

<accordion>
<panel type="info" title="Informar o título. Ex: Agrupamento de títulos" icon="fa fa-caret-right">
Conteúdo que o usuário lerá ao abrir a aba.
</panel>

<panel type="info" title="Informar o título. Ex: Agrupar parcela com a conta financeira" icon="fa
fa-caret-right">
Conteúdo que o usuário lerá ao abrir a aba.
</panel>

<panel type="info" title="Informar o título. Ex: Agrupar somente com os filtros de tela" icon="fa fa-
caret-right">
Conteúdo que o usuário lerá ao abrir a aba.
</panel>
</accordion>

7. Pode-se incluir uma conclusão da documentação abaixo dos tópicos expansíveis, caso julgar necessário:

8. Deve-se incluir a informação de contato com o Suporte, bem como, o botão de Voltar com seus devidos direcionamentos.

Informações adicionais:

• Explicar para que serve a funcionalidade que está sendo documentada. Exemplo: “Esta rotina tem a finalidade de realizar o processo (nome do processo), abaixo um vídeo ilustrativo de como realizar o processo (nome do processo).”
• Informar os filtros, explicar sua funcionalidade, se é obrigatório ou não. Exemplo: “O filtro de (nome do filtro) serve para buscar a informação (nome da informação).”
• Informar os campos, explicar sua funcionalidade, se é obrigatório ou não. Exemplo: “O campo (nome do campo) serve para inserir a informação (nome da informação).”
• Estruturar textos e imagens de forma harmônica, não poluindo a tela com textos extensos e imagens com várias marcações na explicação de uma funcionalidade.
• Ao explicar alguns campos, estes podem ser unificados, quando, por exemplo, existirem os campos de data inicial e final, deve-se unificar e explicar os dois em uma linha somente, como no exemplo abaixo:
  

• Se houver muitas informações a respeito de cada aba, de modo que estas não caibam dentro dos tópicos expansíveis, deve-se criar uma lista de tópicos para cada aba, conforme exemplo abaixo:
  

Para separar os campos e filtros obrigatórios, pode ser separado da seguinte forma:

Observação: Alguns filtros e campos terão que ter exemplo do que pode ser inserido, a fim de ajudar na compreensão para a utilização do campo. Exemplo:

• Em casos de cadastros em que clientes do produto Modular não possuam acesso, deve-se incluir um aviso sobre a rotina não estar disponível para clientes modulares, já no início da documentação, para que o usuário não tenha que ler toda a documentação e só depois descobrir que não conseguirá acessar o cadastro:
  

Os balões de avisos são utilizados para atrair a atenção do leitor para alguma informação importante a respeito da rotina. Por exemplo, quando deseja sinalizar uma informação importante no texto, deve-se utilizar o título Importante: dentro do balão “warning”, que possui a cor amarela, e também, o ícone de alerta, conforme exemplo abaixo:

Existem duas formas de incluir os balões na documentação:

1. Incluir o texto manualmente:

<alert type="warning" dismiss="false" icon="fa fa-warning">\\
**Importante:** (Inserir o texto aqui).\\
</alert>\\

2. Incluir a partir do ícone do Bootstrap, conforme o GIF abaixo:

Observações:

• Para visualizar os demais tipos de balões, cores, ícones e descrições, acesse: Padronização de balões e ícones.
  
• Para visualizar mais ícones que podem ser utilizados na documentação, acesse: https://fontawesome.com/v4.7/icons/
  

• Evitar circular os campos da imagem com a cor vermelha, pois esta cor simboliza erro. O ideal, é destacar os campos com a cor azul.
  
• As imagens não devem ter mais de três anotações em azul.
  
• Ao inserir a imagem, seu tamanho deve ser original. Além disso, quando inseri-la, deve-se escolher a opção “nolink”, e com isso, quando o usuário clicar sobre a imagem, ela não será expandida.
  

• A imagem deve ser coerente com a informação que está sendo passada, e sua qualidade também é importante. Espaçamento entre os textos e as imagens das telas.
• Ao inserir a imagem, o endereço dela ficará da seguinte forma na documentação:
  

1. O nome da documentação – Help Mentor Web.
2. O módulo (Financeiro, Acadêmico, Central do Aluno, entre outros).
3. A operação que seria o menu que está sendo tratado (nome da imagem).
4. “nolink” para que não seja possível expandir a imagem quando clicado em cima.
5. Duas barras (\\) serve para pular uma linha.

• Para circular as informações nas imagens, devemos utilizar alguns critérios:

• Uma forma de sinalizar na imagem quando existe mais de um processo, é enumerar e explicar o processo, por exemplo:

Importante: Para selecionar a cor azul no momento de salvar a imagem (print screen), deve-se realizar os passos abaixo:

• Imagens de botão no meio do texto não devem ser utilizados. Existem algumas documentações que encontram-se neste formato, porém, esta forma já não segue mais o padrão de documentação, portanto, não deve-se mais ser utilizado. Abaixo um exemplo:

• Ao inserir imagens na documentação, verificar se as informações contidas nelas são de caráter fictício, para que não sejam expostos dados e informações verídicas, como: Nome de aluno/responsável, CPF, Telefone, entre outros.
• Utilizar nas imagens, palavras/nomes com coerência, conforme exemplo abaixo:
  

• A utilização de vídeos é importante para facilitar o entendimento do usuário em relação ao comportamento do sistema quando é realizada alguma operação. Desta forma, é importante incluir um vídeo já no começo da documentação, para que esta seja uma das primeiras informações a serem vistas quando acessada a documentação.
• Inserir a seguinte frase a cima do vídeo: “Clique no vídeo para ampliá-lo. Após assisti-lo, pressionar a tecla ESC para sair.”. O vídeo já está em um tamanho adequado, porém, alguns usuários podem ter dificuldade em enxergar, e então, poderão maximizar o vídeo. O cliente deve clicar na tecla ESC, pois em tela, não há um botão “Sair”.
• O vídeo deve vir após a explicação da finalidade da rotina:
  

• O tempo de duração do vídeo não deve ser muito alto, e deve mostrar a rotina específica que está sendo tratada na documentação.
• Os dados que aparecerem no vídeo devem, preferencialmente ser de caráter ilustrativo, sem dados verídicos, e os vídeos devem ser gravados em base local ou na base de demonstração.
• Ao gravar a rotina, deve-se enquadrar a gravação do banner para baixo, para que não apareça os links favoritados na barra de favoritos, nem as abas que estavam em aberto no navegador, e nem mesmo o banner, conforme mostra a imagem abaixo:
  

• Na descrição do vídeo, deve conter o nome do menu, acompanhado do nome do processo que está sendo realizado:
  

Neste caso, a documentação é referente à Consulta de Contas a Pagar, e o nome do vídeo deve ser referente ao processo de consulta de contas a pagar.

Ferramentas de gravação de vídeo e GIF:

• A ferramenta utilizada para gravar GIF é o Gif Record, que deverá ser baixado no computador. Para baixar o programa, deve-se acessar o link http://www.gifrecorder.com/download.htm#.Ykc_Oqhv_cs. Após gravar o GIF, deve-se salvá-lo em sua máquina, e posteriormente, adicioná-lo a documentação.

• A ferramenta utilizada para gravar vídeos é o Screen Recorder, que é um serviço online de gravação de vídeos. Para utilizar, basta acessar o link (https://screencast-o-matic.com/screen-recorder) e seguir com as orientações mostradas em tela.
  
• Posteriormente, este vídeo deverá ser carregado no Vimeo com a conta da Edusoft, e após estes processos, o vídeo poderá ser inserido na documentação.
  

• Assim como as imagens, o vídeo também deverá ser centralizado, e para isso a resolução do vídeo deve ser de 1080×500. Com isso, o endereço na documentação ficará da seguinte forma:
  

1. Local de onde vem o vídeo (Vimeo, Youtube e etc).
2. Endereço de identificação do vídeo.
3. Dimensão do vídeo, que pode ser ajustado, mas o padrão utilizado é 1080×500.
   

Existem alguns procedimentos diferenciados na tecnologia G5, desta forma, para documentá-la, existem alguns procedimentos a serem seguidos:

• Na tecnologia do novo Mentor Web G5, por padrão as telas são carregadas com os campos em branco, na documentação de telas dos módulos que são do novo Mentor Web G5 utilizar o seguinte texto na introdução:
  

“Ao clicar nesta opção, a tela expandida primeiramente é apresentada com os campos em branco. Para inserir um novo indicador, basta preencher as informações obrigatórias.”

• Padronizar nas imagens da nova tecnologia do Mentor Web, a combo de pesquisa conforme imagem abaixo.

Usar a imagem nas telas:

Em algumas telas e rotinas do sistema, existem filtros que aparecem com certa frequência especialmente quando é possível procurar pelo nome e código, e para realizar a busca, é possível procurar com %, então, quando for documentar uma rotina na qual tenha este filtro, pode-se inserir a informação de como procurar com o sinal de %.

“No Mentor Web, é possível efetuar uma pesquisa inserindo os caracteres % antes ou depois da palavra inserida para facilitar a busca da informação correta. Por exemplo:

Para filtrar todos que possuem a palavra maria: %maria%
Para filtrar todos que iniciam com a palavra maria: maria%
Para filtrar todos que terminam com a palavra maria: %maria%
Para filtrar todos que contenham as palavras joão e maria: %joão% maria”

Para finalizar a documentação, é sempre importante incluir a orientação de que o cliente poderá abrir um chamado para nosso suporte no caso da documentação não ter sanado suas dúvidas. Sendo a seguinte orientação:

Ainda há dúvidas? Se você preferir retire suas dúvidas com nosso suporte, clique aqui e abra um chamado para atendimento.

Código para inserir a informação do Softdesk para o cliente:

//Ainda há dúvidas? Se você preferir, retire suas dúvidas com nosso suporte. [[http://suporte.edusoft.com.br|Clique aqui]] e abra um chamado para atendimento.// :-)

• Padronizar as opções de Voltar e Avançar, sendo estas opções apresentadas somente no final da documentação, em forma de botões.
  

Código para inserir os botões:

[[{}[[insira_link_aqui | Voltar]]
[[{}[[insira_link_aqui | Avançar]]

Observações: O link a ser inserido nos botões deverá ser apenas da palavra “help” em diante, conforme imagem abaixo:

• Assim que a documentação estiver concluída, esta deverá ser homologada. Após homologada, será disponibilizada aos clientes no Help Oficial.
• Após ser homologada, o link da documentação deverá ser informado no Metadados, para que quando o cliente for acessar o Help no sistema, já abra na documentação atualizada.
  

A documentação Consulta de parcelas possui vários exemplos de todas as informações acima citadas.