Padronização de escrita do Help

Release notes modelo: Versão 08.13.00

Estrutura do release notes

• O release notes é separado em três blocos principais: Novidades, Melhorias e Ajustes de inconsistências. Cada bloco possui divisões internas por módulo e cada módulo então vai conter os chamados ou atividades realizadas.
• O bloco de novidades deve conter essencialmente os chamados de customização, quando trata-se de novos de recursos ou alterações que impactam na forma de utilização de um recurso existente. O bloco de melhorias, deve conter os chamados que tratam de modificações pequenas e pontuais em recursos já existentes, como inclusão ou alteração de um filtro, posicionamento de campo e etc. Já o bloco de ajustes de inconsistências deve apresentar os chamados que tratam erros em recursos que estão com comportamento inesperado em relação ao previsto.
• Os módulos dentro dos blocos devem espelhar os módulos do sistema, com algumas considerações: Utiliza-se o módulo acadêmico para tratar dos módulos de ensino padrão (Colégio, Graduação e Pós, presencial ou EAD), e ferramentas como Mentor Agendador, Gerador de interfaces, Security, Report também são considerados módulos.
• Considere chamados de processos agendados, relatórios ou interfaces vão estar contemplados nos módulos do sistema ao qual estão diretamente envolvidos em processo, enquanto que alterações nos recursos destes módulos é que serão apresentados dentro deles.
• Os chamados apresentados no release notes SEMPRE devem ser os chamados principais, que foram abertos pelo solicitante. Normalmente será um chamado, contudo em algumas situações, pode ser que um recurso liberado possua dois ou mais chamados que solicitaram o recurso ou parte do recurso liberado. Mesmo que um chamado possua várias TFs, deve-se gerar no release apenas um item no release notes, contendo o resumo de toda a liberação.
• Alguns recursos técnicos que envolvem atualizador, scripts, configurações específicas, tomcat, podem ser colocados em um “Módulo” chamado “Atualização” que se necessário, será o primeiro.

Estrutura do chamado

• Todo recurso liberado deve começar pelo título, que deve destacar em poucas palavras o que foi efetivamente entregue. Por exemplo: “Chat individual entre alunos e professores” ou “Serviço padrão para a integração com catracas”. Normalmente o título do chamado não vai ter uma boa descrição, sendo necessário escrever o mesmo de uma outra forma.
• Após o título, deve ser apresentado o conteúdo que contempla a liberação. Com raras exceções, o texto do recurso no release notes deve ser apenas um parágrafo, mesmo que envolva um grande processo alterações em várias telas. A função de detalhar cada campo e regra é do help. O release notes deve dar ciência ao usuário que um recurso foi liberado. O texto introdutório acaba tornando a leitura mais longa e cansativa, é melhor já ir direto ao ponto no release notes. Lembre-se que menos é mais!
• Na composição do conteúdo, pode-se utilizar o chat GPT para tornar o texto mais amigável, contudo evite deixar o texto longo ou com frase que não agrega ao usuário que vai ler. O usuário vai chegar à conclusão que o processo ficou mais eficiente ou ágil sem que isso esteja escrito. Agora, diferente de mencionar que o recurso ou processo ficou mais eficiente, mencionar que agora é possível filtrar por curso por exemplo, é sim uma informação bem relevante!.
• A user story e a contextualização do documento de análise podem ajudar na composição do release notes, contudo é uma linguagem voltada para o programador e não para o usuário final, portanto o ideal é escrever com as próprias palavras o conteúdo. Faça uma curadoria em cima do documento de análise para replicar de uma forma direcionada ao cliente para help e release.
• Em conjunto, definimos padronizar no release notes uma forma padrão na forma de escrever o texto. Exemplo (“Aprimoramos, Liberamos, Implementamos e afins).
• Após o conteúdo, devem ser apresentados os links que direcionam ao help. Preferencialmente o próprio texto que o usuário lê pode ser o hyperlink, não sendo necessário o famoso “clique aqui”.
• O número dos chamados deve ser colocado no final do texto com fonte itálica como: “Chamado(s) de origem: 212121”.
• Chamados ou parte de chamados que tratam de campos renomeados ou mudanças muito discretas que pouco vão agregar, ou ainda chamados de configurações internas de uso exclusivo da Edusoft, também não devem constar no release notes.

Evite termos técnicos que o usuário comum pode não reconhecer

        Rotina > Processo ou Recurso.
        Parametrizar > Configurar.
        Parâmetro > Configuração ou Opção.
        Checkbox > Caixa de marcação.
        Flag > Caixa de marcação.
        Combo > Caixa de seleção.
        Cli, Pad, Per > Específico, Padrão, Personalizado.
        Procedure ou Funcion > Procedimento de banco de dados.
     

Interfaces PAD e relatórios E

• Toda interface ou relatório deve constar com o nome e o código entre parênteses no release notes.
• Interfaces e relatórios PAD, E devem constar no release notes.
• Se for customização, estará na parte de “Novidades”. Deve-se cuidar com a questão do módulo, deve-se colocar o módulo na qual faz sentido o relatório.
• Se for manutenção, estará na parte de “Ajustes”. Deve-se cuidar com a questão do módulo, deve-se colocar o módulo na qual faz sentido o relatório. Por exemplo, o cliente pode disponibilizar um relatório de “Recebimento” no módulo “Acadêmico”. Porém, é um relatório “Financeiro”. Então, no release ele tem que aparecer no agrupador referente ao módulo “financeiro”.
• Quando for “manutenção” estará sempre vinculado no próximo release notes que será liberado (exceto hotfix). Quando for customização, colocamos no release notes da versão beta/oficial.
• Para chamados do serviço, de manutenção, geralmente eles não tem versão de liberação. Neste caso, quando for chamados de manutenção, vamos começar a ir no chamado pai que está com o suporte e registrar um trâmite com o auto-texto “Liberação de chamado de serviço”.

Interfaces e relatórios P e PER

• Interfaces e relatórios P e PER não devem constar no release notes.
• Depois, caso envolvidos em um processo maior, devem ser incluídos na parte de rotinas específicas do cliente. Isso nem sempre é necessário.
• Interfaces e relatórios C e CLI não devem sequer ser testados pela qualidade e menos ainda liberados. Todo relatório ou interface C ou CLI deve ser convertido para P ou PER.

• Após finalizar a documentação, deve-se incluí-la no Release Notes da próxima versão, a fim de informar aos usuários que tal documentação foi criada/atualizada:

Helps modelo: Processo Seletivo de Bolsa Social
Curriculo Digital
Planilha de dados de modelo: currículo escolar digital

Estrutura do help

• Assim como no release notes, o help também é estruturado em três tipos ou blocos de documentação: Recursos, Processos e Rotinas específicas.
• Os recursos são propriamente as opções de menu do sistema. A documentação dos recursos ou opções de menu informa ao usuário de modo detalhado como cada campo, filtro, botão ou tratamento em tela funciona, sem pensar em contexto de processo ou apenas mencionando pontualmente processos se necessário. O usuário que ler a documentação de um recurso, deve saber o comportamento dos campos, as regras de preenchimento e pontualmente, se for relevante, como se aplica em um processo mais a frente, como por exemplo, a regra de seleção dos atos regulatórios do curso ou da instituição na geração do diploma.
• Já os processos não tratam de uma opção de menu, mas de um conjunto de configurações, operações e relatórios. A documentação dos processos, deve informar ao usuário de modo detalhado os pré requisitos, o sequenciamento dos passos e os resultados esperados, direciona o que precisa ser feito mas não detalha como cada configuração, cadastro ou operação é feita. O usuário quando precisa saber como cada item do processo funciona, deve acessar o recurso. Para isso, em cada passo da documentação do processo, deve haver link direcionando ao recurso para que o usuário tenha acesso a todas as informações no mesmo local.
• Algo muito importante quanto aos recursos e processos, é que tratam-se apenas do que é padrão do sistema e disponível à todos os clientes. Cadastros, processos, relatórios ou interfaces personalizadas a clientes específicos, devem ser documentados nas rotinas específicas do cliente.
• As rotinas específicas por sua vez serão semelhantes aos processos, contudo são específicas de um ou alguns clientes e portanto, não estão visíveis aos usuários, sendo documentada dentro da parte de documentação técnica do help e necessitando assim de login para visualização. Estruturalmente, podem ser semelhantes à documentação do processo. Contudo podem ter dentro no corpo do texto, detalhamento dos recursos se forem também específicos do cliente.
• A diferença fundamental entre o help e o release notes, é que enquanto o release informa em poucas palavras o que foi liberado no sistema, o help além de não estar atrelado a uma versão, ele detalha a informação tanto quanto for necessário, para que o usuário tenha a total compreensão do recurso ou processo.

Dicas gerais para a criação de help

• Para realizar testes e entender a rotina que será documentada, é necessário ter uma base local online disponível. Caso exista documentação antiga sobre a rotina, é importante revisá-la para corrigir erros ortográficos e verificar se ainda está atualizada. É possível que alguns processos tenham sido modificados devido a correções de erros e customizações no sistema, o que pode resultar em mudanças na rotina.
• Verificar se existem chamados abertos relacionados à funcionalidade em questão e avaliar se as informações contidas neles são consistentes e verdadeiras, podendo ser incluídas na documentação.
• Realizar um levantamento das principais dúvidas em cada módulo e documentá-las, mesmo que já exista uma documentação anterior sobre a rotina.
• Conversar com especialistas na rotina, coletar as informações necessárias, estudar o assunto e, então, começar a estruturar a documentação, transferindo as informações para o QualHelp.

Regras de documentação

• Quando houver duas ou três formas de trabalho em um recurso, antes de detalhar cada uma, indicar quais são estas formas, como elas são e para quem atender, para aí então as detalhar;
• Documentação de campos/filtros de tela: Sempre que documentar um campo/filtro, deve informar no que este campo vai influenciar, quando informado/marcado, e quando não informado/desmarcado. E dar um pequeno exemplo de como o fazer. EXEMPLO: Data inicial e final: se informadas, as datas serão atribuídas à validade do desconto incluído ao contrato financeiro do aluno relacionado ao processo de bolsas. Caso não informado, o desconto incluído não terá um prazo de validade definido.
• A documentação de layouts externos como JSONs e XMLs, deve ser feita em planilha de dados disponível por anexo e não fazê-la no help diretamente. Deve conter o nome dos campos do layout externo com regras de preenchimento, quantidade, obrigatoriedade, formato e observações sempre que necessário. Além do layout externo, deve contemplar os dados do Mentor, trazendo a tabela, a coluna, a entidade, o atributo ou em outros casos o campo em tela para preenchimento.
• As imagens devem ter bordas, ser das cores em tom preto e fina, uma vez que o cliente pode customizar a cor desejada no mentor, portanto o preto não chamará tanta a atenção e possuir dados que não exponham clientes e usuários. Além disso, devem ser imagens bem formatadas, onde os nomes e descrições contidas na mesma retratem algo realista. Evite mostrar barra de rolagem lateral nas imagens e informações sem necessidade.
• Quando uma imagem estiver sendo exibida para refletir campos do sistema, procure grifar e enumerá-los, para no texto referenciá-los de forma simples e clara.

Finalização do documento

• Para finalizar a documentação, é essencial incluir uma orientação para que os clientes possam buscar suporte adicional caso suas dúvidas não tenham sido esclarecidas. Sugerimos incluir 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.

É necessário prestar atenção especial à ortografia, evitando erros de português, redundâncias, falta de concordância e pontuação incorreta. Recomenda-se utilizar o LibreOffice para corrigir erros ortográficos. Um erro bastante comum na escrita é não tratar o gênero masculino/feminino da introdução da frase com o seu restante. Por exemplo: “Implementado uma nova tela de geração de parcelas.” Tela é feminino. “Implementada na tela de geração de parcelas um filtro de curso”. Neste caso o filtro que foi implementado é masculino.

A linguagem na documentação deve ser clara, objetiva e rica em detalhes. O objetivo é permitir que o usuário compreenda a explicação e possa realizar o procedimento desejado sem dificuldades.

Deve haver espaçamento adequado entre os textos e as imagens das telas.

Ao explicar um campo de uma tela, nos campos obrigatórios, deve-se usar verbos que indiquem a obrigatoriedade, como “deve-se” ou “é necessário”. Nos campos opcionais, deve-se indicar que são opcionais e que o usuário pode ou não preenchê-los, usando termos como “pode-se”.

É importante separar os textos introdutórios dos itens dos campos de uma tela, usando uma quebra de linha e duas barras invertidas “\”.

Exemplo:

Os títulos e subtítulos devem seguir a seguinte estrutura no Dokuwiki:

• Item de lista não ordenadaTítulo: Utilize seis sinais ”=“ antes e depois do título.
• Item de lista não ordenadaSubtítulo: Utilize quatro sinais ”=“ antes e depois do subtítulo. Adicione quatro sinais ”-“ abaixo do subtítulo para inserir uma linha separadora.

Exemplo:

Em documentações de rotina, utilize cinco sinais ”=“ antes e depois do subtítulo, e adicione quatro sinais ”-“ abaixo do subtítulo para inserir uma linha separadora.

Padronize o uso de plurais nos textos, como por exemplo “o(s) e-mail(s)”, para indicar a possibilidade de um ou vários e-mails.

Durante o processo de estruturação e documentação, adicione a frase “Em construção” ao título, para que os leitores saibam que a documentação ainda não está concluída. Essa informação deve ser removida apenas quando a documentação for homologada e todas as informações estiverem corretas de acordo com a funcionalidade.

Exemplo:

Evite utilizar o termo “Clique aqui” para direcionar o usuário a outra documentação. O Google utiliza as informações de texto âncora para direcionar os usuários aos links relevantes. Portanto, é importante fornecer o nome da rotina ou o título da documentação como texto âncora para que o Google possa redirecionar corretamente o usuário ao link apropriado. O uso do termo “Clique aqui” não é informativo o suficiente para o Google. Veja o exemplo abaixo:

• Detalhar: Exibe todas as informações relacionadas a parcela. Clique no link detalhar parcelas para saber mais.
• Alterar: Efetua a alteração da parcela, podendo recalcular valores, vencimentos, entre outros. Clique no link alterar parcelas para saber mais.
• Cancelar: Para cancelar uma parcela ou um título vinculado a ela, deve-se utilizar essa opção. Clique no link cancelar parcelas para saber mais.
• Renegociar: Nesta opção você poderá efetuar a negociação das parcelas em débito. Clique no link renegociar parcelas para saber mais.

• Procure por sinônimos das palavras para evitar repetições constantes do mesmo verbo. Por exemplo, “deve-se” pode ser substituído por expressões como “em que se”, “tem de se”, “é obrigatório”, “é recomendado”, “é preciso”, “é necessário”.

• Ao detalhar campos e filtros, destaque o nome do filtro utilizando negrito e, ao lado, informe a utilidade do mesmo. Isso pode ser feito da seguinte maneira:

Filtros para parcelas

• Período letivo: ao informar período letivo, serão carregadas parcelas referente à este período.
• Contrato financeiro: ao informar contrato financeiro, serão carregadas parcelas referentes à este contrato.
• Responsável: ao informar responsável, serão carregadas parcelas vinculadas à este responsável.
• Curso: ao informar curso, serão carregadas parcelas vinculadas à este curso.
• Turma: ao informar turma, serão carregadas parcelas vinculadas à esta turma.

• É importante incluir exemplos de situações em algumas rotinas, utilizando como base a realidade do cliente. Isso permite que o cliente compreenda a funcionalidade de forma simples e didática. Veja o exemplo abaixo:

• Não agrupar: Selecione essa opção caso você não queira agrupar os títulos. Nesse caso, cada título será exibido individualmente, sem nenhum tipo de agrupamento.
• Agrupar por responsável e data de vencimento: Selecione essa opção caso você queira agrupar os títulos que possuam o mesmo responsável e a mesma data de vencimento.

Exemplo de um agrupamento: Existem parcelas de mensalidades e de apostilas. As parcelas são de contas financeiras diferentes, porém, tem o mesmo vencimento no mesmo dia. Para que o responsável não precise pagar dois boletos separados, a instituição pode agrupar estes dois boletos, gerando apenas um boleto contendo as duas parcelas.

Links na documentação:

Ao inserir links nos release notes, evite incluir o link completo com https://qualhelp.edusoft.inf.br/doku.php?id=help:mentorweb:modulo_processo:processo_seletivo_de_bolsa_social. Utilize apenas o trecho após o “ID=”, como help:mentorweb:modulo_processo:processo_seletivo_de_bolsa_social, para garantir o acesso adequado do cliente à página.

Exemplo da utilização do link corretamente.

Exemplo da utilização do link Incorretamente.