Artigos
Artigos assinados ou escritos em nome da equipa que explicam o produto sem apagar a engenharia que existe por detrás.
- Textos assinados ou escritos em nome da equipa
- Pesquisa e verificação de fontes
- Edição, metadados e publicação
Escrita técnica e publicação
Escrevo sobre sistemas que consigo realmente compreender.
Sou engenheiro antes de ser redator. Consigo ler o código, questionar a arquitetura, entrevistar quem construiu o sistema e escrever para quem não estava na sala.
Falar sobre um projeto de escritaO que posso entregar
Profundidade técnica sem texto escrito por comité.
Posso partir de entrevistas, código-fonte, notas de produto, pesquisa pública ou de um rascunho correto mas difícil de ler.
Documentação
Documentação de produto e para developers organizada em torno da tarefa, não da estrutura interna da empresa.
- Guias de introdução e conceitos
- Documentação de APIs e integrações
- Arquitetura de informação e manutenção
Relatórios técnicos
Um retrato claro e fundamentado de um sistema, mercado, risco ou decisão técnica para quem tem de agir sobre ela.
- Síntese de pesquisa
- Análise técnica e de produto
- Estrutura e diagramas para apoiar decisões
A minha abordagem
Faço o trabalho técnico antes de escrever.
Começo por perceber o que é verdade, o que continua incerto e o que o leitor precisa de retirar da peça final.
Ler e perguntar
Revejo o código, a documentação, a pesquisa e a história do produto, depois entrevisto quem conhece melhor o assunto.
Encontrar o argumento
Alinho o leitor, a ideia central, o nível de detalhe e as perguntas a que a peça tem de responder.
Escrever e questionar
Redijo com uma voz direta e levo as afirmações incertas de volta a quem as pode verificar.
Fechar a publicação
Preparo o texto final, diagramas, metadados, ligações e entrada no CMS quando a publicação faz parte do trabalho.
É útil quando
A equipa compreende o assunto. O leitor ainda não.
- Um produto precisa de documentação antes de clientes ou developers o conseguirem adotar.
- Uma equipa técnica tem conhecimento, mas não tem tempo para o transformar num bom artigo.
- A pesquisa precisa de se tornar num relatório que um decisor consiga realmente ler.
- Um rascunho está correto, mas precisa de estrutura, edição e publicação.
FAQ
Perguntas sobre escrita técnica
Podes escrever a partir de código-fonte e entrevistas técnicas?
Sim. Posso trabalhar a partir de repositórios, documentação de produto, pesquisa e entrevistas com as pessoas mais próximas do sistema.
Podes tratar da publicação além da escrita?
Sim. A entrega final pode incluir diagramas, metadados, ligações internas, entrada no CMS, estrutura documental e verificações de publicação quando existe acesso.
Podes editar um rascunho técnico existente?
Sim. Posso reestruturar, verificar factos, tornar o texto mais direto e prepará-lo para publicação sem apagar o conhecimento ou a voz do autor.
Há algo difícil de explicar?