Pular para o conteúdo principal

Como estas respostas são escritas

De onde vêm as perguntas das Dúvidas Frequentes​

Todas as perguntas das Dúvidas Frequentes são perguntas reais, feitas por usuários e pontos focais do E-Docs nos canais de suporte: o grupo de pontos focais, os atendimentos da equipe de suporte do APEES e do PRODEST e, à medida que ele for disponibilizado, as perguntas feitas ao tira-dúvidas da documentação. Nenhuma pergunta é inventada para preencher a seção.

Antes de virar uma entrada, cada caso real é generalizado: saem nomes de pessoas, números de processo e setores identificáveis, e fica a situação que qualquer usuário pode viver. O título mantém, sempre que possível, as palavras de quem perguntou ("sobrenome de casada", "milhares de peças", "pasta que parece vazia"), porque é assim que a próxima pessoa vai procurar.

Uma dúvida que ainda não está aqui deve ser levada ao ponto focal do órgão, que pode encaminhá-la aos demais níveis de suporte. Perguntas recorrentes nesses canais são a principal fonte de novas entradas.

O formato de cada resposta nas Dúvidas Frequentes​

Cada entrada segue o mesmo formato:

  • Uma pergunta por título, como ela foi feita.
  • A resposta vem na primeira frase: sim, não ou a causa do problema. Em seguida, só o necessário para resolver o caso: a condição que importa e o que fazer. As respostas são curtas de propósito: a explicação de por que a regra existe fica em Definições e Regras.
  • A resposta se sustenta sozinha: pode ser lida sem ler as perguntas vizinhas nem outras páginas.
  • Mensagens de erro reais aparecem no texto, quando a dúvida nasceu de uma.
  • Limitações conhecidas do sistema são sinalizadas como tal, com o contorno disponível, e revistas quando o sistema é corrigido.
  • Toda resposta termina com o link para a regra em Definições e Regras, para quem quiser se aprofundar.

Como toda a documentação do E-Docs, as respostas descrevem regras e o que a funcionalidade faz, e não telas ou botões, que mudam com frequência.

A relação entre as Dúvidas Frequentes e as Definições e Regras​

As Dúvidas Frequentes não substituem as Definições e Regras. As duas seções têm papéis diferentes:

  • Definições e Regras explica como o E-Docs funciona e por quê, com profundidade, para leitura e estudo.
  • Dúvidas Frequentes resolve uma situação concreta, aplicando a regra ao caso.

A regra é escrita em um lugar só, em Definições e Regras. A resposta aplica essa regra em poucas frases e aponta para ela. Quando uma pergunta revela uma regra que ainda não estava documentada, ela é escrita primeiro em Definições e Regras e só depois ganha a resposta. Assim, as duas seções não se contradizem quando o sistema muda.

As referências técnicas usadas na redação das Dúvidas Frequentes​

A forma das Dúvidas Frequentes segue práticas reconhecidas de documentação técnica e de gestão do conhecimento:

  • Diátaxis: organiza a documentação por tipo de texto, separando a explicação (que ajuda a entender) do guia prático (que ajuda a resolver). É a base da separação entre Definições e Regras e Dúvidas Frequentes.
  • KCS (Knowledge-Centered Service): metodologia de gestão do conhecimento para equipes de suporte, em que o conhecimento nasce do atendimento real, é registrado com as palavras de quem perguntou e melhora com o uso. É a origem da regra de só incluir perguntas reais e do ciclo em que as dúvidas recorrentes alimentam a documentação.
  • Tópicos de solução de problemas do DITA e da documentação do GitLab: o problema no título e, no corpo, a causa e o que fazer.
  • Every Page is Page One (Mark Baker): cada página, e cada resposta, pode ser a primeira que o leitor vê, e por isso precisa se sustentar sozinha.
  • Guias de redação de serviços digitais de governo, como os da Nova Zelândia e do Canadá: alertam que seções de perguntas frequentes tendem a duplicar conteúdo e a desatualizar. As salvaguardas vêm daí: só perguntas reais, regra escrita em um lugar só e revisão sempre que a regra muda.

O formato também foi pensado para o tira-dúvidas da documentação, que responde perguntas a partir de um único trecho do texto. Uma resposta completa e autossuficiente em cada título é o que permite a ele encontrar e entregar a resposta certa.