Como Escrever Documentação de Software

PDF download Baixe em PDF
PDF download Baixe em PDF

Uma boa documentação de software – seja ela para programadores e testadores, para documentos técnicos de usuários internos ou para manuais de software e arquivos de ajuda para usuários finais – ajuda a pessoa trabalhando com o software a entender suas funções e características. Uma boa documentação é específica, concisa e relevante, fornecendo todas as informações importantes para as pessoas usando o programa. Continue lendo para obter instruções sobre como escrever uma documentação de software para usuários técnicos e finais.

Método 1
Método 1 de 2:

Escrevendo documentação de software para usuários técnicos

PDF download Baixe em PDF
  1. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/5\/57\/Write-Software-Documentation-Step-1.jpg\/v4-460px-Write-Software-Documentation-Step-1.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/5\/57\/Write-Software-Documentation-Step-1.jpg\/v4-728px-Write-Software-Documentation-Step-1.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Os documentos de especificação de software servem como manuais de referência para designers da interface do usuário, programadores que escrevem código e testadores que verificam se o software funciona como desejado. As informações exatas dependem do programa em questão, mas podem incluir:
    • Arquivos chave dentro do aplicativo. Eles podem incluir 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. Inclui-se aqui uma explicação do que cada função ou sub-rotina faz, incluindo sua gama de valores de entrada e saída.
    • Variáveis e constantes do programa, e como são usadas no aplicativo.
    • A estrutura geral do programa. Para um aplicativo baseado em disco, isso pode significar descrever os módulos e bibliotecas individuais do programa, enquanto para um aplicativo web, uma descrição de quais páginas usam quais arquivos.
  2. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/6\/6f\/Write-Software-Documentation-Step-2.jpg\/v4-460px-Write-Software-Documentation-Step-2.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/6\/6f\/Write-Software-Documentation-Step-2.jpg\/v4-728px-Write-Software-Documentation-Step-2.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Quanto mais documentação técnica for desenvolvida dentro da fonte do programa, mais fácil será atualizar e realizar manutenção no código, bem como documentar as várias 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, ele pode ser documentado na forma de um arquivo de ajuda, que pode ser indexado ou pesquisado com palavras chave. Essa é uma vantagem em particular para aplicativos nos quais a lógica do programa é fragmentada em muitas páginas e inclui diversos arquivos suplementares, assim como com certos aplicativos web.
    • Algumas linguagens de programação, como Java e .NET Framework (Visual Basic. NET, C #), têm seus próprios programas para documentar códigos. Nesses casos, siga os padrões de quantidade de documentação que deve ser incluída.
  3. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/8\/85\/Write-Software-Documentation-Step-3.jpg\/v4-460px-Write-Software-Documentation-Step-3.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/8\/85\/Write-Software-Documentation-Step-3.jpg\/v4-728px-Write-Software-Documentation-Step-3.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Até um certo ponto, isso será determinado pela linguagem na qual o código é escrito, seja em C++, C# , Visual Basic, Java, ou PHP, pois existem ferramentas específicas para essas e outras linguagens. Em outros casos, a ferramenta a ser usadas é determinada pelo tipo de documentação necessária.
    • Programas de processamento de palavras para o Microsoft Word são adequados para criar arquivos de texto separados, desde que a documentação seja relativamente 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 código fonte podem ser produzidos com qualquer ferramenta de ajuda para escrita técnica, como o RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare, ou HelpLogix.
    Publicidade
Método 2
Método 2 de 2:

Escrevendo documentação de software para usuários finais

PDF download Baixe em PDF
  1. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/8\/85\/Write-Software-Documentation-Step-4.jpg\/v4-460px-Write-Software-Documentation-Step-4.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/8\/85\/Write-Software-Documentation-Step-4.jpg\/v4-728px-Write-Software-Documentation-Step-4.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Apesar da razão funcional ser ajudar usuários a entenderem a usar o aplicativo, há outros motivos também, como ajudar a anunciar o programa, melhorar a imagem da empresa, e, mais importante, reduzir custos de suporte técnico. Em alguns casos, a documentação é necessária para cumprir certos regulamentos ou outras exigências legais.
    • Sob nenhuma circunstância, no entanto, a documentação deve substituir um design de interface ruim. Se uma tela de um aplicativo requer páginas e páginas de documentação para explicá-la, é melhor mudar o design para deixá-la mais intuitiva.
  2. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/3\/35\/Write-Software-Documentation-Step-5.jpg\/v4-460px-Write-Software-Documentation-Step-5.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/3\/35\/Write-Software-Documentation-Step-5.jpg\/v4-728px-Write-Software-Documentation-Step-5.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Na maioria dos casos, usuários de softwares têm pouco conhecimento de computadores além das tarefas dos aplicativos que eles usam permitem. Há diversas maneiras de determinar como satisfazer suas necessidades com sua documentação.
    • Observe os nomes dos trabalhos dos usuários potenciais. Um administrador de sistemas provavelmente é perito em diversos aplicativos de software, enquanto um funcionário de entrada de dados provavelmente conhecerá apenas o aplicativo que usa para inserir dados.
    • Observe os próprios usuários. Apesar dos títulos dos funcionários geralmente indicarem o que as pessoas fazem, pode haver uma variação considerável em como certos títulos são usados dentro de uma certa organização. Entrevistando os possíveis usuários, é possível descobrir se suas impressões sobre suas necessidades são precisas ou não.
    • Observe a documentação existente. A documentação de versões anteriores do software, bem como especificações funcionais, fornecem alguma indicação do que o usuário precisará saber para usar o programa. Tenha em mente, no entanto, que usuários finais não se interessam em como o programa funciona, mas sim pelo que ele pode fazer por elas.
    • Identifique as tarefas necessárias para realizar o trabalho e as que precisam ser realizadas antes delas.
  3. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/5\/5b\/Write-Software-Documentation-Step-6.jpg\/v4-460px-Write-Software-Documentation-Step-6.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/5\/5b\/Write-Software-Documentation-Step-6.jpg\/v4-728px-Write-Software-Documentation-Step-6.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    A documentação de software pode ser estruturada em 1 ou 2 formatos, o manual de referência e guia de usuário. Às vezes uma combinação de formatos é a melhor abordagem.
    • Um formato de manual de referência é devotado a explicar as características individuais de um aplicativo (botões, guias, campos e caixas de diálogo) e como elas funcionam. Muitos arquivos de ajuda são escritos nesse formato, que exibe um tópico relevante sempre que um usuário clicar no botão de ajuda de uma certa tela.
    • Um formato de guia de usuário explica como usar o programa para realizar uma tarefa em particular. Esses guias normalmente são impressos ou exibidos virtualmente em PDFs, apesar de alguns arquivos de ajuda incluírem tópicos de como realizar tarefas em particular (esses tópicos de ajuda geralmente não são sensíveis ao contexto, apesar deles poderem conter links para tópicos que sejam). Os guias de usuário geralmente tomam a forma de tutoriais, com um resumo das tarefas a serem realizadas na introdução e instruções dadas nos passos numerados.
  4. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/d\/d9\/Write-Software-Documentation-Step-7.jpg\/v4-460px-Write-Software-Documentation-Step-7.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/d\/d9\/Write-Software-Documentation-Step-7.jpg\/v4-728px-Write-Software-Documentation-Step-7.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    A documentação de software para usuários finais pode tomar uma de várias ou diversas formas: manuais impressos, documentos PDF, arquivos de ajuda ou ajuda online. Cada forma é feita para mostrar ao usuário como usar cada uma das funções do programa, seja na forma de um walkthrough ou tutorial; no caso de arquivos de ajuda e ajuda online, pode-se incluir vídeos de demonstração, bem como texto e imagens.
    • Arquivos de ajuda devem ser indexados e pesquisáveis por palavras chave para que os usuários encontrem a informação desejada rapidamente. Apesar de ferramentas de escrita poderem gerar índices automaticamente, é melhor fazê-lo manualmente, usando termos que os usuários provavelmente buscarão.
  5. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/f\/fd\/Write-Software-Documentation-Step-8.jpg\/v4-460px-Write-Software-Documentation-Step-8.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/f\/fd\/Write-Software-Documentation-Step-8.jpg\/v4-728px-Write-Software-Documentation-Step-8.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Manuais impressos ou em PDF podem ser escritos com um programa de processamento de palavras como o Word ou um editor de texto sofisticado como o FrameMaker, dependendo do tamanho e complexidade dos mesmos. Arquivos de ajuda podem ser escritos com uma ferramenta específica para arquivos de ajuda, como o RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix, ou HelpServer.
    Publicidade

Dicas

  • O texto deve ser organizado para leitura fácil, com imagens posicionadas próximas do texto relacionado a elas. Divida a documentação em seções e tópicos de forma lógica. Cada seção ou tópico pode ser referenciado com um "veja também" ou links, conforme necessário.
  • As ferramentas de documentação listadas acima podem ser suplementadas com um programa de criação de screenshots, como o Snagit, se a documentação exigir diversos screenshots. Assim como com outras documentações, essas capturas de tela devem ser inclusas para ajudar a explicar como o programa funciona, e não para impressionar o usuário.
  • O tom é particularmente importante, especialmente ao escrever documentação para usuários finais. Chame-os de "você" ao invés de "usuários".
Publicidade

Materiais Necessários

  • Ferramenta de documentação de software/arquivos de ajuda
  • Ferramenta de criação de screenshots

WikiHows Relacionados

Como
Melhorar a Sua Caligrafia
Como
Restaurar Marcadores Ressecados
Como
Escrever na Terceira Pessoa
Como
Criar uma Assinatura Legal
Como
Escrever uma Boa História
Como
Escrever um Diário Pessoal
Como
Escrever com uma Letra Bonita
Como
Ter uma Letra Bonita
Como
Citar um PDF
Como
Descrever a Aparência Física de uma Pessoa
Como
Citar uma Música
Como
Escrever um Discurso de Boas Vindas
Como
Citar um Poema
Como
Criar um Manual do Usuário
Publicidade

Referências

  1. http://www.softwaredocumentation.info/DocumentingSoftware.aspx
  2. http://www.techscribe.co.uk/ta/how-to-write-user-documentation.htm
  3. http://www.techscribe.co.uk/ta/how-to-write-instructions.htm
  4. Rodney Ruff, Omaha, NE; experiência em escrita técnica/autor de arquivos de ajuda desde 1997

Sobre este guia wikiHow

Em outras línguas
Esta página foi acessada 73 886 vezes.

Este artigo foi útil?

Publicidade