Como Escrever Documentação para Software: 8 Passos (com Imagens)

Contente

Degraus
- Método 1 de 2: Escrevendo documentação de software para usuários técnicos
- Método 2 de 2: Escrevendo documentação de software para usuários finais
Pontas
Necessidades

Uma boa documentação de software, seja um documento de especificação para programadores e testadores, um documento técnico para colegas ou manuais de software e arquivos de ajuda para usuários finais, ajuda a pessoa que precisa trabalhar com o software a entender todos os seus recursos e funções. Uma boa documentação de software é específica, concisa e relevante, fornecendo todas as informações importantes para a pessoa que usa o software. Abaixo, você encontrará instruções sobre como escrever a documentação do software para usuários técnicos e usuários finais.

Degraus

Método 1 de 2: Escrevendo documentação de software para usuários técnicos

Imagem intitulada Write Software Documentation Step 1

1. Decida quais informações incluir. As especificações de software servem como guias para designers de interface de usuário, programadores que escrevem o código e testadores que verificam se o software funciona como pretendido. As informações exatas dependem do programa em questão, mas podem incluir qualquer um dos seguintes:

Os arquivos mais importantes dentro do aplicativo. Estes podem ser arquivos criados pela equipe de desenvolvimento, bancos de dados acessados durante a operação do programa e utilitários de terceiros.
Funções e Sub-rotinas. Isso inclui uma explicação do que cada função ou sub-rotina faz, incluindo todos os valores de entrada e saída.
Variáveis e constantes do programa e como elas são usadas no aplicativo.
A estrutura geral do programa. Para um aplicativo baseado em disco, isso pode ser uma descrição dos módulos e bibliotecas individuais do programa, enquanto para um aplicativo da Web, pode descrever quais páginas usam quais arquivos.

Imagem intitulada Write Software Documentation Step 2

2. Decida quanto da documentação deve ser incluída no código do programa e quanto deve ser mantido separado. Quanto mais documentação técnica já foi desenvolvida dentro do código fonte do programa, mais fácil será atualizá-lo e mantê-lo junto com o código, bem como documentar diferentes versões do aplicativo original. No mínimo, a documentação dentro do código-fonte deve explicar o propósito das funções, sub-rotinas, variáveis e constantes.

Se o código-fonte for particularmente longo, pode ser documentado na forma de um arquivo de ajuda, que pode ser indexado e pesquisado com palavras-chave. Essa é uma vantagem particular para aplicativos em que a lógica do programa é fragmentada em muitas páginas e contém vários arquivos adicionais, como certos aplicativos da Web.

Algumas linguagens de programação, como Java e .NET Framework (Visual Basic.NET, C#), têm seus próprios padrões para documentar o código. Nesses casos, siga as normas sobre quanto da documentação deve ser incluída no código-fonte.

Imagem intitulada Write Software Documentation Step 3

3. Escolha a ferramenta de documentação certa. Até certo ponto, isso é determinado pela linguagem em que o código é escrito (como C++, C#, Visual Basic, Java ou PHP), pois existem ferramentas específicas para essas e outras linguagens. Em outros casos, o tipo de documentação exigida determina qual ferramenta usar.

Programas de processamento de texto para Microsoft Word são suficientes para criar arquivos de texto separados para documentação, desde que a documentação seja bastante curta e simples. Para arquivos de texto longos e complexos, muitos escritores técnicos preferem uma ferramenta de documentação como o Adobe FrameMaker.

Arquivos de ajuda para documentar o código-fonte podem ser produzidos com qualquer ferramenta de autoria de ajuda, como RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare ou HelpLogix.

Método 2 de 2: Escrevendo documentação de software para usuários finais

Imagem intitulada Write Software Documentation Step 4

1. Determine os motivos comerciais para sua documentação. Embora a razão funcional para documentar o software seja ajudar os usuários a entender como usar o aplicativo, existem outras razões, como auxiliar na comercialização do software, melhorar a imagem corporativa e, o mais importante, reduzir os custos de suporte técnico. Em alguns casos, a documentação é necessária para cumprir determinados regulamentos ou outros requisitos legais.

No entanto, de forma alguma a documentação do software deve ser um substituto para um design de interface ruim. Se um aplicativo requer páginas de documentação como guia, é melhor alterar o design da tela para algo mais intuitivo.

Imagem intitulada Write Software Documentation Step 5

2. Entenda o público para o qual você está escrevendo a documentação. Na maioria dos casos, os usuários de software têm pouco conhecimento de computadores além das tarefas que podem realizar com os aplicativos que usam. Existem várias maneiras de determinar o que eles precisam e como sua documentação pode atendê-los.

Veja os recursos que seus usuários em potencial têm. Um administrador de sistema provavelmente é um especialista em vários aplicativos de software, enquanto um operador de entrada de dados provavelmente conhecerá apenas o aplicativo que está usando para inserir dados.

Olhe para os próprios usuários. Embora os cargos geralmente indiquem o que as pessoas fazem, pode haver diferenças significativas em como determinados cargos são preenchidos dentro de uma organização. Ao entrevistar potenciais usuários você pode ter uma ideia se sua impressão do que o posicionamento deles indica está correta ou não.

Veja a documentação existente. A documentação das versões anteriores do software (assim como as especificações funcionais) fornecem uma indicação do que o usuário precisa saber para usar o programa. No entanto, lembre-se de que os usuários finais não estão realmente interessados em como o programa funciona, mas no que ele pode fazer por eles.

Determinar as tarefas que devem ser feitas para concluir uma atribuição e quais tarefas devem ser realizadas antes que essas tarefas possam ser executadas.

Imagem intitulada Write Software Documentation Step 6

3. Determinar o formato correto para a documentação. A documentação do software pode ser estruturada em 1 de 2 formatos: o manual e o manual do usuário. Às vezes, uma combinação de ambos os formatos é a melhor abordagem.

Um guia de referência é dedicado a explicar as funções individuais de um aplicativo de software (botões, guias, campos e caixa de diálogo) e como elas funcionam. Muitos arquivos de ajuda são escritos neste formato, especialmente a ajuda contextual que exibe um tópico relevante quando um usuário clica no botão Ajuda em uma tela específica.

Um guia do usuário explica como usar o software para executar uma tarefa específica. Os manuais do usuário geralmente são formatados como guias impressos ou PDFs, embora alguns arquivos de ajuda contenham tópicos sobre como executar determinadas tarefas. (Esses tópicos de ajuda geralmente não dependem do contexto, embora possam estar vinculados a tópicos que são.) Os guias do usuário geralmente vêm na forma de tutoriais, com uma visão geral das tarefas a serem executadas na introdução e instruções fornecidas em etapas numeradas.

Imagem intitulada Write Software Documentation Step 7

4. Decida qual a forma que a documentação deve ter. A documentação do software pode assumir várias formas: manuais, documentos PDF, arquivos de ajuda ou ajuda online. Cada formulário é projetado para mostrar ao usuário o uso de cada um dos recursos do programa, seja na forma de passo a passo ou tutorial; no caso de arquivos de ajuda e ajuda online, pode ser texto, vídeos de demonstração e imagens.

Os arquivos de ajuda e a ajuda online devem ser indexados e pesquisáveis com palavras-chave, permitindo que os usuários encontrem rapidamente as informações de que precisam. Embora os criadores de arquivos de ajuda possam gerar índices automaticamente, geralmente é melhor criar o índice manualmente, usando termos que os usuários geralmente pesquisam.

Imagem intitulada Write Software Documentation Step 8

5. Escolha uma ferramenta de documentação adequada. Manuais impressos ou em PDF podem ser escritos usando um programa de processamento de texto, como o Word, ou um editor de texto avançado, como o FrameMaker, dependendo do tamanho e da complexidade. Os arquivos de ajuda podem ser escritos com uma ferramenta de autoria especial, como RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix ou HelpServer.

Pontas

O texto deve ser organizado de forma a ser de fácil leitura, com imagens o mais próximo possível do texto a que se refere. Divida a documentação logicamente em parágrafos, seções e tópicos. Cada parágrafo ou tópico deve explicar um único problema, seja uma única função do programa ou uma tarefa. Problemas relacionados podem ser explicados, quando apropriado, usando listas ou hiperlinks `Ver também`, conforme indicado acima.
Qualquer uma das ferramentas de documentação listadas acima pode ser complementada com um programa de captura de tela, como o Snagit, se a documentação exigir algumas capturas de tela. Assim como em outras documentações, as capturas de tela devem ser incluídas para ajudar a explicar como o software funciona, para não confundir o usuário.
O tom é muito importante, especialmente ao escrever a documentação do software para usuários finais. Aborde os usuários na segunda pessoa ("você") em vez da terceira pessoa ("usuário").