Tema: technical-writing
-
Documentação de onboarding: o caminho de uma máquina nova até uma alteração integrada
A documentação de onboarding é um único caminho numerado que leva quem chega, pessoa ou agente, de uma máquina sem nada instalado até uma alteração integrada, usando apenas o que está escrito. Cada recém-chegado corrige o que o fez tropeçar, e o caminho tem um responsável e uma data de verificação.
-
As páginas de FAQ merecem seu espaço, e o que evita que se deteriorem?
Pergunta em aberto: o guia de estilo do GOV.UK proíbe FAQs no GOV.UK, pois o conteúdo escrito a partir das necessidades dos usuários dispensa esse formato, enquanto o Nielsen Norman Group defende que as FAQs agregam valor e que a busca raramente basta; que resultados mensuráveis, regras de responsabilidade e verificações de desatualização as equipes registraram para páginas de FAQ em documentação técnica?
-
Diagramas como código com Mermaid: o que faz bem e onde chega ao limite
O Mermaid gera diagramas a partir de texto dentro do Markdown, de modo que ficam junto ao código, aparecem no diff da revisão e são renderizados pelo GitHub e por outros visualizadores. Seus limites são o layout automático, que não permite ajuste fino, o tamanho, as diferenças entre versões do renderizador e a acessibilidade, que exige as palavras-chave explícitas de título e descrição.
-
Como escrever textos de origem que se traduzem bem
Textos de interface e documentação traduzem-se sem problemas quando as frases são unidades completas, as strings nunca são montadas a partir de fragmentos, plurais e placeholders passam pelo framework e se evitam expressões idiomáticas, humor e referências culturais; as restrições decorrem do funcionamento das ferramentas do tipo gettext e do trabalho dos tradutores.
-
Como escrever um documento de design ou RFC sobre o qual os revisores consigam decidir
Um documento de design permite obter uma decisão antes de se escrever código: primeiro o problema, depois objetivos e não objetivos, uma explicação em nível de guia e outra em nível de referência, alternativas com os motivos da rejeição, desvantagens e uma lista explícita de questões em aberto. A estrutura segue o que a PEP 1, o modelo de RFC do Rust e a prática de design docs do Google pedem.
-
Atualizações de status durante incidentes: modelo e cadência
Durante um incidente, uma única pessoa fica responsável pela comunicação e publica atualizações em horários fixos, seguindo um modelo: status, impacto visível para o usuário, o que se sabe, o que está sendo feito e o horário da próxima atualização; a atualização sai no horário mesmo que nada tenha mudado.
-
Normas de comunicação assíncrona para equipes distribuídas
Normas escritas definem qual canal serve a cada tipo de mensagem, em quanto tempo se espera resposta, o que é urgente e onde os resultados ficam registrados; a mensagem em si começa pelo pedido, traz o contexto e é completa o bastante para que quem está em outro fuso horário aja sem precisar de perguntas adicionais.
-
Mensagens de erro que dizem a usuários e agentes o que fazer a seguir
Uma boa mensagem de erro indica o que deu errado usando o valor real, declara a restrição violada e diz o que fazer a seguir; para agentes, inclui ainda um código estável, o campo com falha, se uma nova tentativa pode ajudar e eventuais correções sugeridas, rotuladas com o grau de confiança.
-
Como nomear documentos e arquivos para que ordenem, sejam encontrados e durem
Uma convenção de nomes de arquivos define os componentes do nome e a sua ordem, um único separador, o conjunto de caracteres portável, uma data no estilo ISO que ordena como texto, números de sequência com zeros à esquerda e versões explícitas; é registrada uma só vez por pasta e nunca depende de maiúsculas e minúsculas nem de espaços.
-
Quando as equipes de documentação excluem uma página em vez de atualizá-la, e o que aconteceu depois com leitores e links?
Pergunta em aberto: páginas desatualizadas costumam ser reescritas e raramente removidas; a MDN descreve o status 410 Gone como sinal de que o recurso não está mais disponível e de que a condição provavelmente é permanente, mas a maioria das páginas excluídas vira redirecionamento ou 404. Quais critérios de exclusão as equipes usaram, e o que ocorreu depois com tráfego, resultados de busca e links de entrada?
-
Guia de estilo para referência de API: um único formato para cada entrada
Um guia de estilo para referência fixa a ordem das seções (resumo, sintaxe, parâmetros, valor de retorno, erros, observações, exemplo), a redação da primeira frase e a forma de declarar padrões, restrições e descontinuações, para que leitores e geradores prevejam onde está cada informação.
-
Manter um glossário do projeto como vocabulário compartilhado
Um glossário dá a cada termo do domínio um nome preferido, uma definição, seus quase-sinônimos com as diferenças e um status. Os documentos expandem as siglas no primeiro uso e apontam para o verbete; ao renomear um conceito, o glossário é atualizado na mesma alteração que o código e a documentação.
Legível por máquina: JSON