5 perguntas a se fazer ao escrever a documentação do projeto
Usar alguns dos princípios básicos de comunicação eficaz pode ajudá-lo a criar documentos de projeto informativos e bem escritos que se alinhem com sua marca.
Antes de começar a escrever a documentação de outro de seus projetos de código aberto, e mesmo antes de entrevistar os especialistas, é uma boa ideia responder a algumas perguntas de alto nível sobre seu novo documento.
O renomado teórico da comunicação Harold Lasswell escreveu em seu artigo de 1948, A Estrutura e Função da Comunicação na Sociedade:
[Uma] maneira conveniente de descrever um ato de comunicação é responder às seguintes perguntas:
- Quem
- Diz o que
- Em qual canal
- A quem
- Com que efeito?
Como comunicador técnico, você pode aplicar a teoria de Lasswell e responder perguntas semelhantes sobre o seu documento para comunicar melhor sua mensagem e com o efeito desejado.
Quem—Quem é o proprietário do documento?
Ou qual empresa está por trás do documento? Que identidade de marca ela deseja transmitir ao seu público? A resposta a esta pergunta influenciará significativamente o seu estilo de escrita. A empresa também pode ter seu próprio guia de estilo ou pelo menos uma declaração de missão formal; nesse caso, você deve começar por aí.
Se a empresa está apenas começando, você pode fazer as perguntas acima ao titular do documento. Como escritor, é importante integrar a voz e a personalidade que você cria para a empresa com sua própria visão de mundo e crenças. Isso fará com que sua escrita pareça mais natural e menos parecida com o jargão da empresa.
Diz o quê—Qual é o tipo de documento?
Que informações você precisa comunicar? Que tipo de documento é: guia do usuário, referência de API, notas de versão, etc.? Muitos tipos de documentos terão modelos ou estruturas geralmente acordadas que lhe darão um ponto de partida e ajudarão a garantir a inclusão de todas as informações necessárias.
Em qual canal—Qual é o formato do documento?
Nos documentos técnicos, muitas vezes o canal de comunicação informa o formato final do seu documento, ou seja, se será PDF, HTML, arquivo de texto, etc. seu documento.
Para quem—Quem é o público-alvo?
Quem lerá este documento? Qual é o seu nível de conhecimento? Quais são suas responsabilidades profissionais e seus principais desafios? Essas perguntas o ajudarão a determinar o que você deve cobrir, se deve ou não entrar em detalhes, se pode usar termos específicos, etc. Em alguns casos, as respostas a essas perguntas podem até influenciar a complexidade da sintaxe que você deve usar. .
Com que efeito – Qual é o propósito do documento?
É aqui que você deve definir quais problemas este documento deverá resolver para seus leitores em potencial ou quais perguntas ele deverá responder a eles. Por exemplo, o objetivo do seu documento pode ser ensinar seus clientes a trabalhar com seu produto.
Neste ponto, você pode consultar a abordagem sugerida pela Divio. De acordo com esta abordagem, você pode atribuir a qualquer documento um de quatro tipos, dependendo da orientação geral do documento: aprender, resolver um problema, compreender ou obter informações.
Outra boa pergunta a ser feita neste estágio é qual problema comercial este documento pretende resolver (por exemplo, como reduzir custos de suporte). Com um problema comercial em mente, você poderá ver um ângulo importante para sua redação.
Conclusão
As perguntas acima foram elaboradas para ajudá-lo a formar a base para uma comunicação eficaz e garantir que seu documento cubra tudo o que deveria. Você pode dividi-los em sua própria lista de perguntas e mantê-las sempre que tiver um documento para criar. Esta lista de verificação também pode ser útil quando você ficar preso, confrontado com uma página em branco. Esperamos que isso o inspire e o ajude a gerar ideias.