O que é documentação de software? Tipos e práticas recomendadas para começar

Se você deseja que desenvolvedores e usuários finais obtenham o máximo de valor possível de seu software, você precisa criar uma documentação de software de alta qualidade.

Mas o que é realmente a documentação de software e como você pode criá-la para o seu projeto?

Nesta postagem, vamos nos aprofundar em tudo o que você precisa saber sobre documentação de software, incluindo o seguinte:

• O que é documentação de software?
• Os diferentes tipos de documentação de software (com exemplos)
• Como publicar a documentação do seu software (as melhores ferramentas)
• Algumas práticas recomendadas para criar documentação de software de qualidade

Vamos cavar!

O que é documentação de software?

A documentação de software é o conteúdo que ajuda os usuários finais, desenvolvedores e/ou seus funcionários a entender seu software e usá-lo para atingir seus objetivos de maneira eficaz.

Normalmente, você publicará a documentação do software em seu site. As pessoas podem acessá-lo para saber mais sobre seu software e como ele funciona.

Dentro dessa ampla definição de documentação de software, existem diferentes tipos de documentação de software. Vamos discutir isso a seguir.

Os diferentes tipos de documentação de software

Você pode dividir aproximadamente os diferentes tipos de documentação de software em algumas categorias amplas.

A primeira consideração é a que tipo de pessoa se destina a documentação:

• Documentação do usuário – esta é a documentação que você criou para o usuário final do produto. Isso os ajuda a entender como usar seu software da perspectiva de um usuário comum, que pode ou não ter nenhum conhecimento técnico especial.
• Documentação do desenvolvedor – esta é uma documentação de software mais técnica que você criou para desenvolvedores, como a documentação da API.

A segunda consideração é se a documentação se destina a públicos externos ou internos:

• Documentação de software externo – esta é a documentação voltada para o público que você criou para ajudar seus usuários.
• Documentação de software interno – esta é a documentação privada que você criou para seus funcionários para ajudá-los a trabalhar de forma mais eficaz e compreender os principais detalhes.

Por exemplo, você pode ter um conjunto de documentação do desenvolvedor para suas equipes internas para ajudar a trabalhar no software e outro conjunto de documentação do desenvolvedor voltada para o público para desenvolvedores externos.

Vamos detalhar esses tipos de documentação de software com mais detalhes…

Exemplos de documentação de software para documentação do desenvolvedor

• Documentação da API – mostre aos desenvolvedores como interagir com a API do seu software.
• Readme – apresente seu software e explique o que ele faz – geralmente a primeira coisa que as pessoas leem.
• Notas de lançamento – documente novos lançamentos de seu software, incluindo quaisquer alterações importantes.
• Documentação da arquitetura – mostre a estrutura do seu software, possivelmente incluindo diagramas.
• Documentação do modelo de dados – documente as diferentes estruturas de dados em seu software, incluindo as relações entre diferentes estruturas de dados.
• Documentação do processo – documente os principais processos, como relatórios de bugs, roteiros, garantia de qualidade, protocolos de teste e assim por diante.

Para um exemplo real de documentação de software de documentos focados no desenvolvedor, você pode consultar a documentação “Desenvolvedores” do Gravity Forms, que abrange vários tópicos, como:

• PHP ganchos (para WordPress)
• Objetos de dados
• API do PHP
• Base de dados
• API REST

Por exemplo, veja como é a documentação da API REST:

Exemplos de documentação de software para documentação do usuário

• Guia de primeiros passos – mostre aos usuários como começar a usar seu software rapidamente.
• Tutoriais para casos de uso específicos – tutoriais mais específicos para realizar tarefas específicas.
• Glossários de termos/manuais de referência – ajudam os usuários a entender os principais termos e detalhes.
• FAQs – responda às perguntas mais frequentes.

Para um exemplo real de como pode ser a documentação de software mais focada no usuário, você pode consultar o mesmo exemplo de Gravity Forms acima.

Se você observar os artigos mais focados no usuário do Gravity Forms, verá muitos tutoriais passo a passo sobre como realizar tarefas usando a interface do software, juntamente com glossários e explicações dos principais recursos.

Em comparação com a documentação do software do desenvolvedor, você verá mais capturas de tela e explicações em linguagem simples e muito menos blocos de código.

Como Publicar Documentação de Software: Três Melhores Ferramentas de Documentação de Software

Para publicar sua documentação de software em seu site, você precisará de uma ferramenta de documentação de software dedicada ou algum tipo de sistema de gerenciamento de conhecimento.

Nesta seção, abordaremos rapidamente algumas das melhores ferramentas de documentação de software. Em seguida, na próxima seção, examinaremos algumas práticas recomendadas para a criação de documentação de qualidade.

Se você quiser uma visão mais profunda aqui, leia nossos guias completos sobre as melhores ferramentas de documentação e o melhor software de documentação técnica.

Base de conhecimento heróica

Heroic Knowledge Base é um plug-in de documentação e base de conhecimento para o popular software de código aberto WordPress.

Com o Heroic Knowledge Base, você pode auto-hospedar sua documentação e manter o controle total, enquanto ainda acessa todos os recursos necessários para criar uma documentação de software eficaz.

Aqui estão alguns dos principais recursos que você obtém com a Heroic Knowledge Base:

• Editor de conteúdo flexível , incluindo blocos integrados para textos explicativos e outros detalhes de estilo importantes.
• Índice automático para que os usuários possam ver rapidamente qual conteúdo é abordado em um artigo de documentação e pular para seções específicas.
• Controle de revisão e histórico de versão por meio do sistema de revisão nativo do WordPress.
• Recursos de descoberta de conteúdo , incluindo pesquisa Ajax em tempo real com sugestões ao vivo, categorias e muito mais.
• Sistema de feedback do usuário que permite que as pessoas classifiquem artigos como úteis ou inúteis e compartilhem feedback.
• Análise de pesquisa para que você possa ver o que os usuários estão procurando, bem como quaisquer termos de pesquisa que retornam resultados zero.
• Widget de respostas instantâneas para permitir que os usuários pesquisem e acessem a documentação do software de qualquer lugar em seu site.

Como o Heroic Knowledge Base e o WordPress são auto-hospedados e de código aberto, você também pode modificar sua configuração conforme necessário.

Você pode torná-lo público ou restringir o acesso à sua documentação com várias táticas, como senhas, contas de usuário, endereços IP, uma intranet e muito mais.

Heroic Knowledge Base começa em apenas $ 149 por ano.

Leia os documentos

Read the Docs é uma ferramenta de documentação focada em ajudar você a criar a documentação do desenvolvedor.

Se você estiver focado especificamente na criação de documentação técnica do desenvolvedor, pode ser outra boa opção a ser considerada.

Você pode gerenciar seu conteúdo e histórico de revisão usando o Git e, em seguida, implantar seus documentos em uma interface front-end.

Aqui estão alguns dos outros recursos notáveis ​​em Read the Docs:

• Análise integrada para ver o que seus usuários estão lendo e pesquisando.
• Oferece suporte a várias compilações simultâneas , o que pode ser útil se você oferecer várias versões de seu software – por exemplo, um conjunto de documentação para a versão 1.0 e outro para a versão 2.0.
• Exporte a documentação em diferentes formatos, incluindo PDF, HTML e epub.
• Sugestões de pesquisa ao vivo para ajudar os usuários a encontrar documentos.

O uso do Read the Docs é gratuito se você tiver um projeto de software de código aberto.

Para produtos de software comercial, há um serviço pago Read the Docs for Business que começa em $ 50 por mês.

GitBookGenericName

O GitBook é outra ferramenta de documentação técnica de software que permite gerenciar sua documentação usando o Git, com suporte para os repositórios GitHub e GitLab.

Ou, se você não quiser usar o Git, o GitBook também permite criar sua documentação usando um editor de texto ou importá-la de markdown ou arquivos .doc.

Aqui estão alguns outros recursos notáveis ​​que o GitBook oferece:

• Controle de versão para acompanhar as revisões e o histórico de versões.
• Edição de equipe ao vivo , que é útil se você precisar que vários autores colaborem em artigos.
• Organize artigos usando “espaços” e “coleções” – cada espaço pode ter várias coleções dentro dele.
• Opção de exportação de PDF para que os usuários possam exportar facilmente sua documentação como um download de PDF.

O GitBook é gratuito para projetos sem fins lucrativos ou de código aberto.

Para projetos de software comercial, o GitBook começa em $ 8 por usuário por mês, com um mínimo de 5 usuários. Isso significa que a taxa mensal mais barata é de $ 40 por mês.

Melhores práticas para criar documentação de software

Para terminar, vamos nos aprofundar em algumas práticas recomendadas de documentação de software para ajudá-lo a criar uma documentação eficaz.

Pense nos objetivos e necessidades dos usuários

Ao escrever um artigo de documentação de software, é importante começar respondendo a algumas perguntas básicas:

• Quem é o usuário para quem você está escrevendo?
• O que o usuário está tentando realizar?
• Qual o nível de conhecimento técnico do usuário?

Saber as respostas a essas perguntas ajudará você a entender qual conteúdo abordar e como estruturar o artigo da maneira mais ideal.

Por exemplo, digamos que você oferece um software de agendamento de mídia social e está escrevendo um artigo que ajuda os gerentes de mídia social a agendar sua primeira postagem em mídia social.

Ao escrever a documentação do software, você deve se concentrar em mostrar a maneira mais direta para um usuário final comum atingir esse objetivo.

Se você também oferece uma API para permitir que os desenvolvedores configurem suas próprias integrações, provavelmente deseja abordar isso em um artigo diferente ( embora você possa mencionar e vincular a esse método ).

Inclua a documentação do software no processo de desenvolvimento

Quando você está criando documentação de software, é fácil cair na armadilha de esperar até que um projeto seja concluído para documentá-lo.

No entanto, isso pode levar rapidamente a um débito de documentação porque você pode estar lançando novos recursos ou alterações antes de serem documentados.

Para evitar isso, torne a documentação de software uma parte consciente do ciclo de desenvolvimento de software. Se um novo recurso ou produto ainda não foi documentado, ele não está pronto para ser lançado, mesmo que o próprio código esteja concluído.

Ao tornar a documentação um requisito básico do processo de desenvolvimento de software, você pode garantir que tudo o que você enviar seja acompanhado pela documentação adequada.

Use formatação e estilo consistentes

Para ajudar as pessoas a trabalhar com mais eficiência com a documentação do software, é importante que você use formatação e estilo consistentes em toda a documentação.

O uso da mesma formatação permite que os leitores aprendam como a documentação do seu software está estruturada, o que facilitará o acesso rápido às informações de que precisam.

Para ajudar a alcançar essa consistência, você pode querer criar um guia de estilo de documentação de software dedicado.

Sua ferramenta de gerenciamento de documentação de software também pode incluir recursos para ajudá-lo a obter um estilo consistente.

Por exemplo, o plug-in Heroic Knowledge Base inclui textos explicativos pré-estilizados para destacar as principais informações ou avisos. Ao usá-los, você pode garantir uma formatação consistente em toda a sua documentação.

Use especialistas para escrever documentação técnica

Para documentação de software voltada para o usuário, talvez você não precise de especialistas no assunto para escrever o conteúdo.

No entanto, para documentação de software mais técnica, como documentação de API focada no desenvolvedor, você provavelmente desejará designar alguém com o conhecimento técnico relevante para escrever esses documentos.

Pode ser um redator técnico dedicado com experiência no domínio, se sua organização tiver os recursos para contratar para essa posição. Ou pode ser um de seus desenvolvedores.

O importante é que o escritor entenda os aspectos técnicos do seu software em um nível profundo o suficiente para explicá-lo a outros usuários técnicos.

Facilite a descoberta de conteúdo pelas pessoas (pesquisa/filtro)

À medida que sua biblioteca de documentação cresce, fica mais difícil para os usuários encontrar os artigos de documentação que atendem às suas necessidades.

Para tentar evitar esse problema, concentre-se em melhorar a capacidade de descoberta da documentação do seu software.

Uma primeira estratégia é dividir sua documentação por tipo.

Por exemplo, você normalmente deseja separar a documentação do usuário final da documentação do software do desenvolvedor.

Dentro disso, você também pode usar categorias para dividir ainda mais os artigos. Você pode usar categorias com base em recursos, casos de uso, complementos e assim por diante – o que fizer sentido lógico para o seu produto de software.

De acordo com o mesmo exemplo do Gravity Forms acima, você pode ver que o Gravity Forms divide sua documentação do usuário final por tipos de recursos.

Outro recurso de descoberta útil são as sugestões de pesquisa ao vivo. Os usuários podem começar a digitar uma consulta relevante na caixa de pesquisa e ver instantaneamente os artigos de documentação que correspondem a essa consulta.

Muitas ferramentas de documentação incluem funcionalidade de pesquisa ao vivo integrada, incluindo Heroic Knowledge Base.

Mantenha a documentação do seu software atualizada

Como seu software está sempre mudando, a documentação do software sempre será um trabalho em andamento.

À medida que as coisas mudam em seu software, você precisará atualizar imediatamente sua documentação para refletir essas mudanças.

Caso contrário, sua documentação não será apenas “inútil”, mas pode estar criando confusão em seus usuários.

Para garantir que essas atualizações aconteçam, você deve designar pessoas específicas como proprietárias da documentação e do processo de atualização. Dessa forma, não há ambiguidade sobre quem é responsável por manter tudo preciso.

Use o feedback do cliente para melhorar sua documentação

Além de ter sua própria equipe trabalhando na revisão e atualização da documentação do software, você também deve levar em consideração o feedback do cliente.

Os clientes podem fornecer informações valiosas sobre o quão útil (ou potencialmente inútil) um determinado artigo de documentação de software é, juntamente com detalhes sobre como você pode melhorá-lo.

Para automatizar o processo de feedback do cliente, você deve procurar uma ferramenta de gerenciamento de documentação que inclua recursos integrados para feedback do cliente.

Por exemplo, o plug-in Heroic Knowledge Base permite que os usuários classifiquem um artigo como útil ou inútil e, opcionalmente , forneçam feedback de forma livre.

Você pode visualizar todas essas informações em seu painel para identificar rapidamente os artigos de documentação que precisam ser aprimorados.

Comece a documentar seu software hoje

A documentação do software ajuda você e seus clientes a trabalhar com mais eficiência e obter mais valor de seu software.

Existem diferentes tipos de documentação de software, então você deve pensar em quais tipos atendem às necessidades do seu projeto de software.

Você pode ter documentação diferente para equipes internas ou externas, bem como para diferentes tipos de clientes, como desenvolvedores versus usuários finais.

Para criar uma documentação eficaz, siga as práticas recomendadas desta postagem.

Para publicar essa documentação, você pode usar uma ferramenta de código aberto como a Heroic Knowledge Base, que é baseada no poderoso software WordPress.

Você obterá a flexibilidade e a propriedade de uma plataforma auto-hospedada, com todos os recursos e funcionalidades necessários para publicar documentação de software de alta qualidade.

Se você quiser saber mais, clique aqui para acessar a Heroic Knowledge Base.