Documentação do projeto

Deve conter todos os aspectos que o criador precisa de saber e que não podem ser recebidos diretamente do código. Estes incluem o que fazer e o que não fazer no desenvolvimento, instruções completas de implantação, descrições de integração externa e assim por diante. Este post irá guiá-lo na criação de um ficheiro README poderoso, bonito e legível para o seu projeto.

Uma boa introdução para uma documentação de projeto bem preparada pode ser encontrada nos guias do github: https://guides.github.com/features/wikis/. Isto afirma que "README deve conter apenas a informação necessária para que os programadores comecem a utilizar e a contribuir para o projeto".

Com isso em mente, vamos apresentar uma lista de componentes e melhores práticas que seguimos na Codest para criar a documentação do projeto.

Introdução rápida

- Título do projeto: este é um item obrigatório em todos os README.

- Distintivos de estadoSe utilizar quaisquer medições externas da qualidade do código, testes automatizados ou outras ferramentas, o início do documento é um bom local para mostrar aos outros se funcionam.

- DescriçãoIncluir algumas frases sobre o projeto para descrever rapidamente o seu objetivo principal e as suas funções.

Índice

Uma lista de conteúdos pode ser útil para ficheiros de documentação longos, mas se o seu README é bastante conciso então não é necessário.

Informações gerais

- Sobre a secçãoDescrição do projeto: deve ser uma descrição mais detalhada do projeto - pode incluir informações sobre os utilizadores, as suas funções, alguns casos mais confusos, capturas de ecrã, etc.

- Maquetas: um local para ligações a recursos de maquetas de UI/UX, caso existam.

• Outras informações como Acesso aos servidores ou Integração com APIs externasExemplos incluem o endereço URL de uma instância de teste, credenciais de acesso partilhadas não sensíveis (!), ligações para documentação, algumas instruções, etc.

Instalação

- RequisitosPré-requisitos que devem ser cumpridos antes de iniciar a configuração de uma aplicação, por exemplo, a instalação de ferramentas externas.

- Configuração: uma instrução passo a passo a seguir para pôr o projeto a funcionar.

- DefiniçõesDescrição das definições locais: descrevem o local onde as definições locais são armazenadas e fornecem instruções sobre como receber as suas próprias definições.

- Configuração localSe houver alguns casos de configuração local, este é um bom sítio para uma explicação.

Desenvolvimento

Esta secção é o local ideal para instruções como o desenvolvimento de funcionalidades, correcções de erros, correcções a quente, funcionalidades comuns, testes, guias de estilo, organização do código, outras ferramentas de desenvolvimento utilizadas no projeto (por exemplo, guards ou dockers), etc. Não se esqueça de mencionar todas as regras que cada equipa membro deve saber.

Implantação

Fornecer instruções passo a passo claras para cada ambiente e tudo o que é "bom saber" ao efetuar a implementação.

Outras ideias para secções separadas

- Documentação da API

- Registo de alterações

- Recursos externos: um lugar para todo o tipo de ligações que possam ser úteis.

- Pilha de aplicaçõeslista da pilha de aplicações que utilizamos no projeto - pode conter uma breve descrição e o nome do fornecedor.

Equipa

É discutível se é necessário mostrar os membros actuais da equipa do projeto (o github fornece a lista completa de contribuidores por defeito), mas é sempre agradável ver o seu nome como um dos autores de um projeto. Se o fizer, mantenha-o o mais atualizado possível.

Algumas palavras finais

Lembre-se: cada projeto é único e a sua documentação também. Não existe uma grande solução para escrever um README. Basta seguir as dicas gerais, e a coisa mais importante é sempre lembrar sobre refatoração, que também se conecta ao README. É sempre uma boa ideia olhar para o documento como um todo e repensá-lo se algo precisar de ser apresentado de uma forma diferente.

Mais uma coisa: as "instruções" são fundamentais, por isso escreva-as muitas vezes. Obrigado!

Ler mais:

• Princípio aberto-fechado. Alguma vez terei de o usar?
• Como escrever um código bom e de qualidade?
• Vuelendar. Um novo projeto da Codest baseado no Vue.js