Uma excelente documentação de software impulsiona a adoção, reduz a carga de suporte e ajuda os programadores a integrar mais rapidamente. Com a Trupeer, pode poupar horas na criação de documentação de software começando com um modelo gratuito de documentação de software, personalizando-o com as suas diretrizes de marca e transformando conteúdos técnicos longos em percursos em vídeo que envolvem todos os públicos.

O que é um modelo gratuito de documentação de software?

Um modelo gratuito de documentação de software é uma estrutura reutilizável para registar como funciona uma peça de software, para as pessoas que precisam de a utilizar, integrar, operar ou manter.

A expressão esconde um problema que causa a maioria das falhas na documentação de software. A documentação de software não é um único documento. São pelo menos seis, escritos para leitores diferentes com perguntas diferentes, e uma equipa que se propõe a escrever "a documentação" acaba por produzir algo que serve apenas metade de cada um.

O modelo não é a documentação. O que determina se a sua funciona é saber qual dos seis está a escrever, quem a lê e se alguém alguma vez viu essa pessoa a tentar utilizá-la.

A formatação segue o tipo. Um documento Word de um modelo gratuito de documentação de software serve para documentos de design, especificações e tudo o que é revisto e aprovado. A documentação de referência pertence a um sistema de documentação ou é gerada a partir do código, e não num documento. Um PDF de um modelo gratuito de documentação de software serve para um entregável versionado entregue a um cliente. Uma versão Excel de um modelo gratuito de documentação de software serve para inventários e matrizes de rastreabilidade, em vez de texto corrido.

A documentação de software são seis documentos, não um

Organizados por leitor, porque o leitor determina tudo o resto.

Para começar. Para alguém que não tem nada, mas precisa de que uma coisa funcione. Leia do início ao fim, uma vez. É o documento mais curto que vai escrever e aquele que decide se alguém vai ler os outros.

Referência. Para alguém que está a integrar e precisa de saber o que faz um endpoint, função ou definição específica. Nunca se lê de forma linear; procura-se sempre. A completude é mais importante do que o texto. É frequentemente gerada.

Guias e how tos. Para alguém que tem uma tarefa em mente. Organizados pelo que está a tentar alcançar, e não por funcionalidade — a distinção abordada na página do guia de referência rápida.

Arquitetura e design. Para alguém que a mantém ou a estende, muitas vezes anos mais tarde. O único documento cujo valor principal é explicar o porquê em vez do quê, porque o quê está no código e o porquê está na memória de alguém.

Documentação operacional. Para quem a executa. Deploy, configuração, monitorização e o que fazer quando falha. O runbook cobre a parte executável disto.

Notas de versão e changelog. Para toda a gente. A documentação mais barata de escrever e a mais consistentemente ignorada.

Por isso, o melhor modelo gratuito de documentação de software é aquele que corresponde ao tipo de documento que está a escrever. Dois destes são lidos e quatro são procurados, que é a divisão prática. Para começar e arquitetura são lidos. Referência, guias, documentação operacional e notas de versão são consultados quando há necessidade.

Tentar servir dois destes com um único documento produz a falha característica: uma página demasiado detalhada para começar e demasiado narrativa para consultar.

Como personalizar este modelo na Trupeer

Passo 1: Abrir a secção de Modelos

Aceda à secção de Modelos no menu principal.

Passo 2: Selecionar e abrir um modelo

Clique em qualquer modelo com que pretenda trabalhar para o abrir.

Passo 3: Expandir a visualização do modelo

Se necessário, expanda a visualização do modelo para ver o layout completo e os detalhes com clareza.

Passo 4: Editar o modelo

Clique em Editar para começar a modificar o modelo selecionado.

No editor, pode:

• Adicionar novas secções

• Definir ou atualizar regras de formatação

• Adicionar um logótipo e ajustar a sua posição e definições relacionadas

Passo 5: Guardar o seu modelo personalizado

Depois de fazer todas as alterações necessárias, clique em Guardar para guardar o modelo atualizado como seu.

Passo 6: Pré-visualizar e afinar o modelo

Quando quiser ver como fica o seu modelo personalizado, abra a Pré-visualização.

A partir do ecrã de pré-visualização, pode continuar a fazer ajustes diretamente, se necessário, garantindo que o modelo aparece exatamente como o pretende.

Com um modelo de documentação de software pode:

• Poupar horas na escrita: Ignore a página em branco com uma estrutura criada para documentação de software.

• Abranger todos os públicos: Secções para utilizadores finais, administradores, programadores e equipas de suporte.

• Manter-se fiel à marca: Aplique o seu logótipo, fontes e cores usando o kit de marca da Trupeer.

• Reduzir a carga de suporte: Uma documentação clara ajuda utilizadores e programadores a resolverem por conta própria.

• Atualizar facilmente: Edite uma vez e a Trupeer regenera o vídeo automaticamente.

• Atingir utilizadores globais: Traduza a documentação de software para 65+ idiomas com um único clique.

O único teste: tempo até ao primeiro sucesso

Aqui está a métrica que quase nenhuma equipa mede e que custa uma tarde.

Encontre três pessoas que representem o seu leitor e que não tenham usado o software. Dê-lhes a documentação e um resultado inicial definido: fazer uma chamada de API ter sucesso, fazer o deploy de uma instância, concluir um workflow. Observe-as, em silêncio, e registe o tempo.

Não ajude. A vontade de ajudar é esmagadora e qualquer intervenção destrói os dados. Anote onde hesitam, o que abrem, o que procuram e o ponto exato em que desistem, se o fizerem.

Disto saem três coisas de forma fiável.

O número em si, que normalmente é várias vezes superior ao que a equipa esperava e é o valor a melhorar.

O local da perda, que quase sempre se concentra. Na maioria dos testes, a maior parte do tempo decorrido é gasta em um ou dois obstáculos, e raramente são os que a equipa previu.

E a natureza do obstáculo, que normalmente é algo que ninguém pensou em documentar porque não faz parte do software. Uma chave que tem de ser solicitada. Uma permissão que tem de ser concedida. Um valor predefinido errado. Conhecimento institucional que se tornou invisível para todos os que o detêm.

A documentação de referência não pode ser testada desta forma, uma vez que é introduzida em vez de lida. Teste de outra maneira: pegue nas dez perguntas de suporte mais comuns e meça quanto tempo demora a encontrar cada resposta na documentação. Qualquer coisa acima de trinta segundos é um achado.

O que um modelo de documentação de software tem de conter

Componentes para o documento de para começar, porque é o que decide se qualquer outra coisa é lida.

A linha dos pré-requisitos é a que apanha a maioria das equipas. Qualquer coisa que exija que uma pessoa conceda algo é invisível para quem já tem isso, e é o local mais comum onde um novo leitor fica bloqueado.

Modelo gratuito de documentação de software: a estrutura para copiar

Preenchido com um exemplo real em vez de placeholders. Este é um documento para começar para uma API de logística.

Copie a partir daqui.

Para quem é. Um programador que está a integrar o rastreio de envios num sistema existente. Assume que consegue fazer pedidos HTTP e analisar JSON. Assume que não tem conhecimentos prévios da nossa plataforma.

O que terá no final. Uma chamada bem-sucedida que devolve dados de rastreio em tempo real para um envio de teste, em cerca de quinze minutos.

Pré-requisitos. Uma chave de sandbox, que gera por si no portal do programador em cerca de trinta segundos. Não é necessária aprovação e não é necessário enviar-nos um email. Uma referência de envio, para a qual pode usar a referência de teste fornecida no passo três.

Passos.

1. Gere uma chave de sandbox no portal do programador. Deve ver uma chave que começa com sk_test_. Se vir uma chave que começa com sk_live_, está no portal de produção, que exige um contrato assinado.

2. Guarde a chave como uma variável de ambiente. Não a coloque no controlo de código-fonte.

3. Faça a sua primeira chamada usando o exemplo copiável abaixo, substituindo apenas a sua chave. A referência do envio de teste já está incluída.

4. Deve receber uma resposta de duzentos com um corpo JSON que contém um campo de estado com o valor in_transit. Se receber um quatro zero um, a sua chave não foi lida a partir do ambiente, que é a causa mais comum.

5. Altere a referência do envio para qualquer outra referência de teste na página de dados de teste e repita.

Exemplo que funciona. Valores reais, copiáveis, com apenas a chave substituída.

Falhas comuns. Quatro, retiradas dos nossos pedidos de suporte em vez de serem imaginadas. Quatro zero um, que quase sempre significa que a chave não está a ser lida a partir do ambiente. Quatro zero três, que significa uma chave live contra um endpoint de sandbox. Quatro zero quatro numa referência válida, o que significa que os dados da sandbox são repostos todas as noites e está a usar a referência de ontem. Timeout, que significa que está a chamar o endpoint regional fora dessa região.

Para onde ir a seguir. Apenas dois links. O guia de rastreio, se quiser webhooks em vez de polling. A referência completa, se já sabe qual endpoint precisa.

Versão e última verificação. Versão 4, passos executados pela última vez de ponta a ponta a 3 de junho por um programador que não os tinha visto antes.

Copie para aqui.

Essa última linha vale a pena adotar de forma geral. Uma página de documentação que inclui uma data em que alguém a seguiu efetivamente é consideravelmente mais fiável do que uma que inclui uma data em que alguém a editou.

Exemplo de documentação de software: trezentas e quarenta páginas e três horas

A Portwood Systems, uma empresa com cerca de noventa pessoas que vende uma API de logística a transitários, tinha uma documentação de que toda a gente se orgulhava em silêncio.

Trezentas e quarenta páginas de material de referência, geradas a partir do código, completas e corretas. Todos os endpoints, todos os parâmetros, todos os códigos de resposta. Foi um investimento deliberado e era, de facto, uma excelente documentação de referência.

Os pedidos de suporte de clientes que ainda estavam a integrar representavam cerca de quarenta por cento de todos os pedidos.

Alguém acabou por executar o teste. Três programadores em instalações de clientes, nenhum dos quais tinha usado a API, pediu a cada um que fizesse uma chamada bem-sucedida enquanto um membro da equipa da Portwood observava e não dizia nada.

A expetativa privada da equipa era de vinte minutos.

A primeira demorou três horas e dez minutos. A segunda desistiu após duas horas e enviou um email ao suporte. A terceira demorou uma hora e cinquenta.

Os três perderam mais de quarenta minutos no mesmo local, e não era na API.

A autenticação exigia uma chave de sandbox. As chaves de sandbox eram emitidas por email para o endereço de suporte, com um tempo de resposta de cerca de dois dias. Isto não aparecia em lado nenhum da documentação. A referência documentava o formato do cabeçalho de autenticação com precisão, e nada em lado nenhum dizia que tinha de obter uma chave, muito menos como.

Todas as pessoas na Portwood já tinham uma chave. Várias nunca tinham precisado de a solicitar. Esse passo tinha-se tornado invisível por dentro, que é o que acontece aos pré-requisitos em qualquer organização quando se dá tempo suficiente.

As trezentas e quarenta páginas estavam completas como referência e não continham um caminho do nada até a uma chamada que funciona. A referência responde o que faz este endpoint. Ninguém tinha escrito nada a responder "não tenho nada; como é que faço isto funcionar uma vez".

A correção foi uma página e um pequeno trabalho de engenharia. Seis passos, geração de chaves por autoatendimento em substituição do pedido por email, um exemplo copiável com valores reais e quatro falhas comuns retiradas do histórico dos tickets.

Re-testado com mais três programadores: catorze minutos, vinte e dois minutos, dezoito minutos.

Os pedidos de suporte de integração caíram cerca de sessenta e dois por cento no trimestre seguinte. O tempo mediano desde a assinatura do contrato até à primeira chamada de produção de um cliente passou de trinta e um dias para nove.

Nada estava errado nas trezentas e quarenta páginas. Simplesmente nunca tinha existido uma primeira página.

Como escrever documentação de software em seis passos

1. Decida qual dos seis documentos está a escrever, e escreva-o num único local. Um documento que serve dois leitores não serve nenhum.

2. Identifique o leitor e o que assume que ele sabe. Na escrita, no topo. É isto que torna o conhecimento assumido visível para o autor.

3. Escreva primeiro o documento para começar, mesmo que seja o mais curto. Ele determina se qualquer outra coisa é lida.

4. Liste os pré-requisitos, incluindo qualquer coisa que exija outra pessoa. Depois, remova o máximo que a engenharia conseguir remover, porque cada um é um ponto de bloqueio medido em dias, e não em minutos.

5. Retire os casos de falha dos pedidos de suporte, não da imaginação. Os seus dez tickets mais comuns são o seu backlog de documentação, já priorizado.

6. Teste observando alguém, em silêncio. Tudo o que está acima é suposição até ter o número.

O passo seis é todo o método. Os outros cinco são como responde ao que ele lhe diz.

Manter a documentação de software atualizada

A documentação dá errado em silêncio. Nada o alerta, e a pessoa que descobre isso é, normalmente, um cliente.

Três mecanismos funcionam, por ordem crescente de fiabilidade.

Datas de verificação. Registe quando alguém seguiu os passos pela última vez, e não quando a página foi editada pela última vez. Uma data de edição diz-lhe que alguém mudou uma palavra. Uma data de verificação diz-lhe que funcionou.

Associar as atualizações a versões, e não a um calendário. Uma revisão trimestral da documentação encontra problemas até três meses depois de aparecerem. Um item de documentação na checklist de versão encontra-os antes de serem enviados, que é o argumento apresentado na página de requisitos de versão, onde a documentação deve estar entre os requisitos de prontidão que bloqueiam, e não entre os opcionais.

Gerar o que pode ser gerado. A documentação de referência produzida a partir do código não se pode desviar. É por isso que a documentação de referência é normalmente a parte mais precisa e menos útil de um conjunto de documentação, e por isso que as partes escritas por humanos são onde vivem os erros.

As partes que não podem ser geradas são as que precisam de mais atenção: para começar, guias e tudo o que contém uma captura de ecrã. Essas também são as partes que se degradam mais depressa, porque as interfaces mudam com mais frequência do que as APIs.

Documentação de software ou documentação de projeto?

Estas são pesquisadas em conjunto e são coisas diferentes.

Documentação de software descreve o software: como funciona, como utilizá-lo, como operá-lo. Os seus leitores são utilizadores, integradores e engenheiros, e ela sobrevive ao projeto que a produziu.

Documentação de projeto descreve o projeto: âmbito, plano, decisões, riscos, estado, aprovações. Os seus leitores são partes interessadas e auditores, e fica praticamente concluída quando o projeto termina. Um download gratuito de um modelo Word de documentação de projeto vai dar-lhe estatutos, relatórios de estado e registos de decisões, que são úteis e não são documentação de software. O modelo de documentação de projeto cobre esse lado.

As duas ficam confusas na transição, quando um projeto termina e alguém tem de continuar a executar o que foi construído. Essa transição precisa especificamente de documentação de software, e a falha comum é entregar um arquivo completo do projeto que não contém qualquer documentação operacional.

O que um modelo gratuito de documentação de software não consegue corrigir

Não saber quem a lê. Todas as decisões estruturais resultam do leitor, e nenhum modelo gratuito de documentação de software para download consegue dizer-lhe quem é o seu.

Pré-requisitos que ninguém consegue ver. O problema da Portwood. Só ao observar um elemento externo é que estes se revelam, porque toda a gente de dentro já os ultrapassou e se esqueceu.

Documentação escrita por quem tem tempo. A pessoa com capacidade é frequentemente a que está mais afastada do trabalho. A documentação escrita por alguém que não executa a tarefa vai descrever a sequência pretendida em vez da sequência real.

Um produto que precisa de tanta explicação. Por vezes, o problema da documentação é um problema do produto. Se para começar for genuinamente necessário seguir quarenta passos, vale a pena levantar isso com quem é responsável pelo produto, mesmo que a documentação ainda tenha de ser escrita.

Mostre o software em vez de o descrever

A documentação de software é a categoria em que a diferença entre descrever e mostrar é maior e em que o custo de manutenção para a fechar é mais elevado.

Escrever um passo, capturar a captura de ecrã, recortá-la e anotá-la, colocá-la corretamente e depois fazer tudo isso de novo quando a interface muda é a razão pela qual a maior parte da documentação de software que se pretendia visual acaba por ser texto com uma única captura de ecrã no topo. As interfaces mudam a cada poucas semanas. As capturas de ecrã não.

A Trupeer AI remove esse custo. Alguém executa a tarefa uma vez enquanto grava, e o resultado é um percurso escrito passo a passo com capturas de ecrã já capturadas e colocadas, juntamente com um vídeo, na sua própria marca. A versão escrita torna-se o guia. O vídeo é o que um novo utilizador vê antes de tentar, que é exatamente o material que reduz o tempo até ao primeiro sucesso.

Grave. Dê marca. Traduza. Trupeer.

Há três coisas que daí resultam e que são importantes especificamente para software. Regravar após uma mudança de interface é mais rápido do que voltar a fazer capturas de ecrã, pelo que a documentação visual pode, de facto, ser mantida em vez de ser abandonada. A mesma gravação produz o mesmo percurso em todas as línguas que suporta, pelo que os utilizadores internacionais não trabalham a partir de uma versão mais antiga da verdade. E a gravação é feita pela pessoa que executa a tarefa, que é a correção para a documentação escrita por quem tinha capacidade.

O material fica na sua base de conhecimento e funciona também como formação para suporte e onboarding. O detalhe operacional ao nível da tarefa pertence às instruções de trabalho. A consistência entre os seus documentos é uma questão de definir o kit de marca uma vez, e a configuração é abordada no guia de configuração do modelo de documento.

Perguntas Frequentes

Existe um modelo gratuito de documentação de software em versão Word?

O Word serve os tipos de documentação que são revistos e aprovados: documentos de design, registos de arquitetura, especificações e tudo o que é entregue contratualmente. Um ficheiro Word de um modelo de documentação de software funciona bem para esses casos.

Não serve bem para documentação voltada para o utilizador. Guias e material de referência precisam de ser pesquisáveis, com links e atualizáveis por várias pessoas, o que é um sistema de documentação e não um documento. Se o seu manual do utilizador for um ficheiro Word enviado por email aos clientes, espere que existam várias versões em circulação dentro de um ano.

Existe uma versão Word de um modelo gratuito de documentação de software?

Sim, e um ficheiro Word de um modelo gratuito de documentação de software é o mesmo que um ficheiro Word com uma extensão mais antiga. A escolha que importa não é a extensão, mas sim qual dos seis tipos de documento está a produzir.

Para documentos de design e arquitetura, um documento está certo. Para qualquer coisa que um utilizador ou um integrador lê, publique em vez de enviar, para que exista uma versão atual e não uma por destinatário.

Existe um modelo gratuito de documentação de software em PDF?

O PDF serve para um entregável versionado: documentação entregue a um cliente numa versão, anexada a um contrato, ou arquivada para uma versão regulamentada de um produto.

Não o use para nada que os utilizadores leiam de forma rotineira. Os PDFs não são pesquisáveis entre páginas da forma como um site de documentação é, não fazem links de forma limpa e um cliente que tem um PDF não tem forma de saber que existe um mais recente. Publique a versão atual e exporte um modelo gratuito de documentação de software em PDF apenas quando for realmente necessário um registo fixo.

Existe uma versão Excel de um modelo gratuito de documentação de software?

O Excel serve para inventários em vez de texto corrido. Um ficheiro Excel de um modelo gratuito de documentação de software funciona para uma matriz de cobertura de documentação, uma matriz de rastreabilidade que liga requisitos a testes, um inventário de endpoints de API, ou uma lista do que existe e quando foi verificado pela última vez.

Esse último uso é genuinamente valioso e raramente é feito. Uma linha por documento, com o respetivo tipo, responsável, leitor e data da última verificação, dir-lhe-á mais sobre o estado da sua documentação do que ler qualquer uma das partes.

Existe um download gratuito de um modelo de documentação de software que valha a pena usar?

A lista de secções demora vinte minutos a construir, pelo que um download gratuito de um modelo de documentação de software está a poupar muito pouco, e a maior parte do que é publicado é um esqueleto genérico de documento em vez de algo específico para software.

Se usar um, verifique se distingue entre tipos de documento. Quase nenhum o faz, e essa distinção é a primeira decisão a tomar. Um modelo que oferece uma única estrutura para toda a documentação de software está a propor exatamente o erro contra o qual esta página argumenta.

Onde posso obter um modelo Word gratuito de documentação de projeto?

Isso é um documento diferente. A documentação de projeto cobre o projeto: estatuto, âmbito, plano, registo de riscos, registo de decisões, relatórios de estado e aprovações. A documentação de software cobre o software e sobrevive ao projeto.

Um download gratuito de um modelo Word de documentação de projeto vai dar-lhe o primeiro. Se está no fim de uma fase de construção e está a pensar no que precisa de entregar, precisa de ambos, e a documentação operacional é a metade que mais frequentemente falta num arquivo de projeto.

Qual é o melhor modelo gratuito de documentação de software?

O melhor modelo gratuito de documentação de software é aquele que corresponde ao documento específico que está a escrever, o que significa decidir se está a produzir para começar, referência, um guia, arquitetura, documentação operacional ou notas de versão antes de escolher qualquer coisa.

Se quiser um único teste para comparar opções, veja se o modelo pergunta quem é o leitor e o que é assumido como conhecimento. Esses dois campos fazem mais pelo documento final do que qualquer quantidade de estrutura de secções.

Quanto tempo deve ter a documentação de software?

Para começar deve ter uma página e, se não for possível, os pré-requisitos são a coisa a corrigir, e não a escrita.

O resto deve ter o mesmo tamanho do software. A documentação de referência para uma API grande pode legitimamente ter centenas de páginas, e isso está bem porque ninguém a lê de forma linear. O erro é julgar um conjunto de documentação pelo seu tamanho total, o que não lhe diz nada. Avalie pelo tempo que um recém-chegado demora a chegar ao primeiro sucesso.