18 Ferramentas de Documentação de Software que Fazem o Trabalho Difícil Para Você

🟢 Material de Bônus: Git Workflow Checklist para simplificar & racionalizar a gestão de versões

Sem documentação, o software é apenas uma caixa negra. E as caixas pretas não são tão úteis como poderiam ser porque o seu funcionamento interno está escondido daqueles que precisam delas ao ar livre.

Documentação do software transforma o seu software numa caixa de vidro, explicando aos utilizadores e programadores como funciona ou é utilizado.

Você provavelmente já viu documentação antes, mas se você precisar de uma atualização, aqui está um exemplo da API da Slack:

Como você pode ver, a Slack explica tudo sobre sua API com detalhes excruciantes. Qualquer página relacionada é ligada, há uma barra lateral com tópicos de fácil acesso, e screenshots do que o usuário pode esperar ver.

Para explicar isso com mais detalhes, vamos cobrir os seguintes tópicos neste post da Process Street:

• O que é documentação de software?
• Opções de hospedagem de documentação de software
• Ferramentas de escrita para documentação de software
• Palavras finais sobre documentação de software

Vamos começar.

O que é documentação de software?

“Documentação em engenharia de software é o termo guarda-chuva que engloba todos os documentos e materiais escritos que tratam do desenvolvimento e uso de um produto de software” – Prototype.io, Tipos de Documentação de Software e Melhores Práticas

Todos os pedaços de software devem ter alguma forma de documentação que explique, em detalhes, o que é o produto, como ele funciona e porque ele funciona dessa forma.

“Se não está documentado, não existe” – Sitepoint, A Guide to Writing Your First Software Documentation

Como desenvolvedor, seu objetivo principal é escrever o melhor código que você puder. Você quer que seu código seja melhor na classe, fácil de ler, fácil de usar, e quer que grandes coisas aconteçam como resultado disso. Certo?

But without documenting what you’ve done and why you’ve done it:

• Ninguém mais pode usar o seu código senão você

Sem documentação, ninguém vai entender o que você fez e porque você o fez. Vai ser incrivelmente difícil, negh-on impossível, para outra pessoa pegar no seu código e trabalhar nele. Eles podem até mesmo raspá-lo e começar de novo, pois, em alguns casos, isso seria mais rápido do que tentar descobrir o que você fez e por quê.

• Você não pode atualizá-lo ou melhorá-lo

Você consegue se lembrar do que comeu no jantar de sábado, três meses atrás? A menos que você seja uma criatura completa de hábitos, é provável que não consiga. Então é justo dizer que você provavelmente não se lembrará do código que você escreveu, dois, três, quatro meses depois de tê-lo feito. Se você não consegue se lembrar das razões por trás das suas decisões de codificação, então você vai lutar para ser capaz de atualizá-lo ou melhorá-lo.

Embora isso, a documentação do software é frequentemente uma tarefa que é apressada, mal feita, despriorizada, ou totalmente esquecida.

Antes de começarmos a falar sobre quais ferramentas você pode usar para escrever documentação de software, precisamos pensar em uma maneira de garantir que a tarefa seja feita em primeiro lugar.

É aqui que a Process Street pode ajudar.

Process Street é um software de gestão de processos de negócio (BPM) que pode ser usado para criar, gerir e seguir processos.

Mais sobre o que é Process Street mais tarde, por enquanto, deixe-me mostrar como você pode usá-lo como uma ferramenta para ajudá-lo a encaixar a documentação do software em cada projeto de desenvolvimento de software em que você trabalha.

Below é um exemplo de um modelo de Processo de Implantação de Software pré-fabricado. Este template foi criado para ajudar engenheiros de software e programadores a implementar o seu software da melhor maneira possível.

Clique aqui para acessar o Processo de Implementação de Software!

Para obter este template, faça o login e adicione-o ao seu dashboard, ou inscreva-se para uma avaliação gratuita.

Este template é um exemplo perfeito de um processo que você pode seguir toda vez que quiser implantar um pedaço de código novo ou atualizado.

Tem passos claros que o guiarão por todo o processo de implementação, desde a configuração de um ambiente de encenação até a colocação das suas alterações ao vivo. Estes passos garantirão que nada será perdido e que todo o processo transcorra sem problemas a cada vez.

Desenhamos este modelo para ser usado como um guia para ajudá-lo a criar um processo de implementação que funcione para você. Cada empresa é diferente, cada projecto de software é diferente, e cada processo de implementação é diferente.

Você pode editar este processo e adicionar as tarefas que são relevantes para você, sua empresa, e seu projeto.

Que me traz de volta à documentação do software; você pode adicionar ‘documentação do software’ como uma tarefa. Dessa forma, qualquer pessoa que trabalhe com o processo de implantação do software será lembrada e encorajada a completá-lo, como parte do processo.

Eu tenho mais alguns modelos de processos pré-fabricados que podem ser úteis para vocês, que eu incluirei no final deste post.

Antes de chegarmos a isso, vamos ver onde você pode armazenar sua documentação de software.

Opções de hospedagem de documentação de software

Não é bom ter apenas um monte de arquivos de texto vivendo no seu computador. Eles precisam ser acessíveis por desenvolvedores e usuários, o que você provavelmente vai fazer hospedando os documentos na internet, já que não é a década de 1980.

Process Street (para uso interno)

Para treinar novos desenvolvedores e manter sua documentação vivendo tudo no mesmo lugar, Process Street é uma escolha sólida para documentação de software.

Primeiro, você poderia criar um processo para escrever sua documentação, para garantir que você capture todos os detalhes corretos e torná-la o mais útil possível.

Usando os seguintes recursos fáceis de usar, você pode então escrever e armazenar sua documentação em um único lugar:

• Widgets de imagem
• Widgets de texto
• Widgets de vídeo
• Widgets de arquivo
• Subtarefas
• Widgets de e-mail
• Widgets embutidos

Armazenar a sua documentação dentro da Process Street significa que pode ser acessada por todos na empresa. Você pode compartilhá-la com outros, enviá-la para aprovação, definir lembretes para revisá-la e atualizá-la facilmente.

Check it out:

Se puder ser documentado, pode ser documentado em Process Street.

Inscreva-se para um teste gratuito aqui e experimente-o.

Ler The Docs

É notável que Ler The Docs é gratuito quando você vê tudo o que pode fazer. Similar ao GitHub, você pode criar tanto material open-source quanto você gosta que é indexado abertamente no site, mas vai lhe custar se você quiser tornar os documentos privados e internos à sua empresa. Para nossos propósitos, é provável que você fique bem em ter os documentos prontamente disponíveis para os usuários na web.

>

A razão de ler The Docs é tão boa é que você pode importar sem esforço documentação de qualquer sistema de controle de versão, incluindo Git, Mercurial, Subversion, e Bazaar. Ele também suporta webhooks para que os documentos sejam compilados automaticamente sempre que você submeter código.

Cheque o guia Getting Started deles para ter uma idéia de como ele funciona e como seus documentos se comportariam quando hospedados lá.

GitHub (& GitHub Pages)

Se você está usando GitHub para gerenciar o controle de versão do seu software, você tem, no mínimo, um arquivo README.MD no repositório. Para usar o GitHub para documentar seu software, como milhões de outros já fizeram no passado, basta preencher esse README com markdown.

Um ótimo exemplo é o repositório t do sferik, screenshotted aqui:

Se você quiser mais de uma folha de texto formatado, você pode tirar vantagem da ferramenta Páginas do GitHub (você recebe uma página web gratuita + hospedagem com cada conta GitHub, e você pode até mesmo rotear um domínio personalizado para ele). Páginas tem até temas padrão que fazem sua documentação parecer profissional.

Acima está a documentação atom.io para Electron hospedada no GitHub. É uma escolha inteligente porque funciona automaticamente com o controle de versão do GitHub, assim como o resto do seu software. Veja o repositório do site aqui.

Dropbox Paper (para uso interno)

Para uso interno da documentação do software, o Dropbox Paper é uma excelente escolha. Como seu predecessor Hackpad, você pode usá-lo para criar um wiki privado para funcionários. Você pode unir documentos, inserir blocos de código, imagens e saltos de página, assim como você exigiria de qualquer ferramenta de documentação.

Como você pode ver nos comentários à direita, você também pode usá-lo para passar por processos de aprovação e colaborar na criação da documentação. No geral, é uma ótima ferramenta para desenvolver e criar internamente a documentação, talvez com o objetivo de publicá-la mais tarde, ou apenas mantê-la para uso interno.

Atlassian REST API Browser (para uso de API)

Atlassian’s REST API Browser (RAB) está incluído no JIRA Server, Confluence Server e Stash instâncias por padrão. É construído para descobrir APIs disponíveis para uso em ambientes JIRA/Confluence, e também um lugar para hospedar sua documentação. Se, claro, a sua API se encaixa na factura.

Documentar a sua API usando esta ferramenta para dar mais exposição à sua API JIRA/Confluence compatível. Verifique aqui a documentação da Atlassian sobre como fazer isso.

Tettra (para uso interno)

Tettra é um tipo de software de base de conhecimento onde você pode documentar seu desenvolvimento, ou qualquer coisa.

Usamos Tettra internamente na Process Street para um monte de casos de uso. Dia a dia, eu uso o Tettra para ter um único lugar onde todos os meus processos são documentados para que eu nunca esqueça como um se relaciona com outro ou como as várias automatizações que construímos foram configuradas.

Tettra é ótimo se você estiver procurando criar uma biblioteca de tipos. Isto significa que é brilhante para documentação de software ou mesmo como um wiki interno para a sua empresa.

Dado que o Tettra foi especificamente projetado para a gestão do conhecimento, ele vem com uma série de outras funcionalidades de suporte também. Por exemplo, ele pode fazer sugestões sobre que conteúdo extra ou seções você pode querer adicionar para dar uma imagem mais completa da sua orgia e como as coisas se encaixam.

Você pode ver um pequeno vídeo aqui para ver como uma equipe de desenvolvimento pode parecer para usar o Tettra: Como Produto & Equipas de Engenharia usam Tettra.

Or, você pode ir aqui para ler sobre como nós usamos Tettra ao lado de Process Street: Automatizando Workflows e Checklists: Process Street Case Study.

Check it out!

Apiary (para uso de API)

Além de ser um lugar onde as abelhas vivem, o Apiary é um host dedicado para documentação de API. Escreva em markdown, adicione chamadas de API simuladas e o Apiary cola isso em algo como você vê abaixo:

Anyone pode testar a API sem ter que entrar no aplicativo ou realmente programar uma chamada, o que a torna uma forma super acessível de compartilhar sua API, documentá-la em profundidade e se gabar do que ela pode fazer.

Discutimos onde armazenar sua documentação de software, agora é hora de ver como escrevê-la.

Ferramentas de escrita para documentação de software

A documentação do software é frequentemente escrita em markdown para permitir hiperligações e formatação enquanto a mantém em texto simples para que possa viver ao lado dos ficheiros de código no controlo de versões. Isso significa que muitas das minhas escolhas para ferramentas de escrita são simples editores de markdown que tornam a experiência de escrita agradável. Além disso, há também um par de soluções muito eficazes de não-mparkdown que são lançadas lá.

MarkdownPad (Windows)

Com uma versão gratuita e premium – ambas com uma tonelada de grandes funcionalidades – MarkdownPad é o editor de markdown mais popular para Windows. Está optimizado para posts em blogs, websites, artigos, READMEs e, claro, documentação de software.

>

Você pode obter o MarkdownPad gratuitamente, ou obter a versão premium por $14.95.

iA Writer (Mac)

iA Writer é um editor markdown simples e bonito com uma funcionalidade de biblioteca, o que significa que você pode facilmente referenciar de volta outros documentos na barra lateral. Faltam links internos entre documentos como você esperaria que houvesse em documentos de software, mas você sempre pode fazer uma passagem naqueles quando está em sua forma final (ou seja, se vai acabar na internet em um site).

Se você escrever toda a sua documentação em uma página quebrada, você pode usar âncoras de salto de página para ajudar os usuários a navegar.

iA Writer custa $9.99 da Mac App Store.

Profs Knowledge Base

Profs Knowledge Base é uma pequena e fantástica ferramenta para todos os estágios da criação de documentos; desde escrever e editar, até customizar, configurar fluxos de trabalho e publicar. Você pode adicionar multimídia, importar conteúdo existente de documentos Word, PDF ou PPTs, salvar múltiplas versões do documento e restaurá-los quando necessário.

Mas a verdadeira beleza desta ferramenta reside na sua capacidade de utilização. Qualquer pessoa e todos podem usá-la para construir a documentação do software. Se você tem documentado software há anos ou só começou recentemente, é uma ferramenta incrivelmente simples e fácil de usar.

ProProfs é de uso livre, ou você pode atualizar para o pacote premium que é $112 por mês.

SimpleMDE (navegador)

Embora você possa tecnicamente escrever markdown em qualquer editor de texto porque é uma forma de formatar texto simples, não estritamente uma ‘ferramenta’, não vai surpreendê-lo que também é possível no seu navegador! SimpleMDE é um editor markdown funcional construído em JavaScript e um projeto open-source para aprender e adaptar para seu próprio uso, se necessário.

SimpleMDE é 100% gratuito! Obtenha o código fonte no GitHub aqui.

reStructuredText editors

Markdown é uma das duas linguagens mais usadas para escrever documentação de software, mas há outra que ainda não vimos até agora, e que é a reStructuredText. É muito semelhante ao markdown, mas vale a pena aprender para fins de documentação de software.

Docutils, o criador do reStructuredText, elaborou aqui uma lista de editores do reStructuredText, que inclui:

O ponto do reStructuredText é que é fácil de converter entre diferentes formatos, especialmente do texto simples para um site estático. Veja mais informações aqui.

Ferramentas para gerar automaticamente documentação a partir do código fonte

Não há nada como o toque humano quando se trata de documentação (está claro nos documentos de Slack e Giphy, para citar alguns). Entretanto, como ponto de partida (especialmente para grandes bibliotecas de código fonte), é melhor gerar a documentação do esqueleto automaticamente. Este trabalho analisa as funções e comentários da fonte, e há algumas opções diferentes, dependendo da linguagem:

Antes de ir em frente e confiar somente na geração automática, eu sugeriria a leitura deste thread StackExchange que pesa os prós e os contras.

Palavras finais na documentação do software

Existem bastantes soluções extravagantes, correcções rápidas e ferramentas que são (muito honestamente) quase idênticas. O que importa no final é que

O que mais importa, no final, é isso:

a) você escreve documentação de software para cada software que você constrói
b) você o escreve de forma abrangente e o hospeda em algum lugar que o usuário possa acessar

Eu mencionei anteriormente que eu tinha mais alguns templates de processo de desenvolvimento que você poderia estar interessado em verificar?

Bem, aqui estão eles…

Process Street templates de processos de desenvolvimento

Antes de lhe dar estes templates, deixe-me explicar o que é Process Street um pouco mais.

Então sabemos que a Process Street é super-poderosa lista de verificação. É uma peça de software que o ajudará a criar e gerir processos.

Mas espere, há mais para Process Street do que isso!

Veja este vídeo de introdução para descobrir o que eu quero dizer:

Então você vê, não só pode criar um modelo de processo de desenvolvimento e executar listas de verificação individuais a partir dele toda vez que você precisa completar o processo de desenvolvimento, mas você pode personalizá-lo usando estas características extras

• Parar tarefas
• Datas de vencimento dinâmicas
• Permissões de tarefas
• Lógica condicional
• Tarefas de avaliação
• Aplicação de widget incorporado
• Atribuições de rotação

Atribuir tarefas, obter aprovação, impor uma ordem para que as tarefas sejam concluídas e você pode conectar o processo a milhares de aplicativos via Zapier, webhooks ou integração API.

Veja este webinar sobre nossas mais novas funcionalidades e veja como você pode obter o máximo deles:

Com tudo isso em mente, dê uma olhada nos templates pré-fabricados abaixo:

Lista de verificação de auditoria de segurança da rede

Este template pode ser usado por um gerente de risco ou profissional de TI equivalente para avaliar uma rede quanto a vulnerabilidades de segurança.

Clique aqui para acessar a Lista de verificação de auditoria de segurança da rede!

>

Lista de verificação de manutenção mensal do site

Utilize esta lista de verificação de manutenção mensal do site para otimizar a velocidade de carregamento do seu site, verificar vulnerabilidades e rever sua visibilidade de pesquisa.

>

Clique aqui para acessar a Lista de verificação de manutenção mensal do site!

Tutorial de testes de software

>

Este processo pode ser usado para gerenciar todo um projeto de desenvolvimento de software do início ao fim, incluindo design, manipulação do cliente e também verificações pós-lançamento.

Clique aqui para acessar o Tutorial de Teste de Software!

E lá você tem.

Você agora está livre para usar o que facilitar a sua vida. Espero que você encontre a sua nova ferramenta favorita nesta lista.