Uma boa documentação de software, seja uma documentação de especificação para programadores e testadores, documentos técnicos para usuários internos ou manuais e arquivos de ajuda para usuários finais, ajudará os usuários a compreender os recursos e funções do software. Boa documentação é aquela específica, clara e relevante, com todas as informações de que o usuário precisa. Este artigo irá guiá-lo para escrever a documentação do software para usuários técnicos e usuários finais.
Etapa
Método 1 de 2: escrever documentação de software para usuários técnicos
Etapa 1. Saiba quais informações incluir
O documento de especificação é usado como um manual de referência para designers de interface, programadores que escrevem código e testadores que verificam o desempenho do software. As informações que precisam ser incluídas dependem do programa que está sendo criado, mas podem incluir o seguinte:
- Arquivos importantes no aplicativo, como arquivos criados pela equipe de desenvolvimento, bancos de dados acessados durante a execução do programa e aplicativos de terceiros.
- Funções e sub-rotinas, incluindo uma explicação do uso da função / sub-rotina, valores de entrada e saída.
- Variáveis e constantes do programa e como são usadas.
- Estrutura geral do programa. Para programas baseados em drive, pode ser necessário descrever cada módulo e biblioteca. Ou, se você estiver escrevendo um manual para um programa baseado na web, pode ser necessário explicar quais arquivos cada página usa.
Etapa 2. Decida qual nível de documentação deve estar presente e separável do código do programa
Quanto mais documentação técnica estiver incluída no código do programa, mais fácil será atualizá-la e mantê-la, bem como explicar as diferentes versões do programa. No mínimo, a documentação no código do programa deve incluir o uso de funções, sub-rotinas, variáveis e constantes.
- Se o seu código-fonte for longo, você pode escrever a documentação em um arquivo de ajuda, que pode então ser indexado ou pesquisado com certas palavras-chave. Arquivos de documentação separados são úteis se a lógica do programa for dividida em várias páginas e incluir arquivos de suporte, como um aplicativo da web.
- Algumas linguagens de programação (como Java, Visual Basic. NET ou C #) têm seus próprios padrões de documentação de código. Nesses casos, siga a documentação padrão que deve ser incluída no código-fonte.
Etapa 3. Selecione a ferramenta de documentação apropriada
Em alguns casos, a ferramenta de documentação é determinada pela linguagem de programação usada. As linguagens C ++, C #, Visual Basic, Java, PHP e outras possuem suas próprias ferramentas de documentação. No entanto, caso contrário, as ferramentas utilizadas dependerão da documentação necessária.
- Um processador de texto como o Microsoft Word é adequado para criar arquivos de texto de documentos, desde que a documentação seja concisa e simples. Para criar documentação extensa com texto complexo, a maioria dos escritores técnicos escolhe uma ferramenta de documentação especializada, como Adobe FrameMaker.
- Os arquivos de ajuda para documentar o código-fonte podem ser criados com um programa gerador de arquivo de suporte, como RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare ou HelpLogix.
Método 2 de 2: escrever documentação de software para usuários finais
Etapa 1. Conheça os motivos comerciais subjacentes à criação do manual
Embora o principal motivo da documentação do software seja ajudar os usuários a entender como usar o aplicativo, há vários outros motivos que podem estar na base da criação da documentação, como ajudar o departamento de marketing a vender o aplicativo, melhorar a imagem da empresa e reduzir o suporte técnico custos. Em alguns casos, a documentação é necessária para cumprir os regulamentos ou outros requisitos legais.
No entanto, a documentação não é um bom substituto para uma interface. Se um aplicativo requer muita documentação para funcionar, ele deve ser projetado para ser mais intuitivo
Etapa 2. Conheça o público-alvo da documentação
Geralmente, os usuários de software têm conhecimento limitado de computador além dos aplicativos usados por eles. Existem várias maneiras de atender às necessidades de documentação:
- Preste atenção ao título do usuário do software. Por exemplo, o administrador do sistema geralmente entende vários aplicativos de computador, enquanto a secretária conhece apenas os aplicativos que ele usa para inserir dados.
- Preste atenção aos usuários de software. Embora seus cargos sejam geralmente compatíveis com as tarefas desempenhadas, esses cargos podem ter cargas de trabalho diferentes, dependendo do local de trabalho. Entrevistando usuários em potencial, você pode descobrir se sua avaliação do cargo está correta.
- Preste atenção à documentação existente. A documentação e as especificações da funcionalidade do software podem mostrar o que os usuários precisam saber para usá-los. No entanto, lembre-se de que os usuários podem não estar interessados em conhecer as "entranhas" do programa.
- Saiba o que é necessário para concluir uma tarefa e o que é necessário antes de concluí-la.
Etapa 3. Determine o formato apropriado para a documentação
A documentação do software pode ser organizada em 1 ou 2 formatos, nomeadamente livros de referência e manuais. Às vezes, combinar os dois formatos é uma boa solução.
- Os formatos de referência são usados para descrever todos os recursos do software, como botões, guias, campos e caixas de diálogo, e como eles funcionam. Alguns arquivos de ajuda são escritos neste formato, especialmente aqueles que são sensíveis ao contexto. Quando o usuário clica em Ajuda em uma determinada tela, o usuário receberá o tópico relevante.
- O formato do manual é usado para explicar como fazer algo com o software. Os manuais são geralmente impressos ou em formato PDF, embora algumas páginas de ajuda também incluam instruções sobre como fazer certas coisas. (Geralmente, os formatos manuais não são sensíveis ao contexto, mas podem estar vinculados a tópicos sensíveis ao contexto). Os manuais são geralmente na forma de um guia, com um resumo das tarefas a serem realizadas em uma descrição e um guia formatado em etapas.
Etapa 4. Decida sobre o tipo de documentação
A documentação do software para usuários pode ser empacotada em um ou mais dos seguintes formatos: manuais impressos, arquivos PDF, arquivos de ajuda ou ajuda online. Cada tipo de documentação é projetado para mostrar a você como usar as funções do software, seja um guia ou um tutorial. A documentação online e as páginas de ajuda também podem incluir vídeos de demonstração, texto e imagens estáticas.
Os arquivos de ajuda e suporte online devem ser indexados e pesquisáveis usando palavras-chave para que os usuários possam encontrar rapidamente as informações de que precisam. Embora um aplicativo gerador de arquivo de ajuda possa criar um índice automaticamente, ainda é recomendável que você crie um índice manualmente usando palavras-chave comumente pesquisadas
Etapa 5. Selecione a ferramenta de documentação apropriada
Manuais impressos ou PDFs podem ser criados com um programa de processamento de texto como o Word ou um editor de texto avançado como o FrameMaker, dependendo do comprimento e da complexidade do arquivo. Os arquivos de ajuda podem ser escritos com um programa de criação de arquivos de ajuda, como RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix ou HelpServer.
Pontas
- O texto da documentação do programa deve ser estruturado de forma que seja fácil de ler. Coloque a imagem o mais próximo possível do texto apropriado. Divida a documentação por seções e tópicos de maneira lógica. Cada seção ou tópico deve descrever um problema específico, tanto a tarefa quanto os recursos do programa. Os problemas relacionados podem ser explicados com links ou listas de referência.
- Cada uma das ferramentas de documentação descritas neste artigo pode ser complementada por um programa criador de capturas de tela, como o SnagIt, se sua documentação exigir várias capturas de tela. Como qualquer outra documentação, você também deve incluir capturas de tela para ajudar a explicar como o aplicativo funciona, em vez de "atrair" o usuário.
- Prestar atenção ao estilo é muito importante, especialmente se você estiver escrevendo documentação de software para usuários finais. Dirija-se aos usuários com o pronome "você", em vez de "usuário".
