Sempre que sou solicitado a encontrar e incorporar algum terceiro para um recurso (por exemplo, um serviço de mensagens de texto em massa para que possamos enviar mensagens aos nossos membros), a primeira coisa que descubro sobre cada candidato em potencial é “sua API tem boa documentação?” Isso ocorre porque a documentação ruim pode ser um pesadelo absoluto . Em alguns casos, é mais fácil criar o recurso do zero do que tentar descobrir a documentação.
Você pode gastar bem mais de $ 1000 dólares na configuração certa de hardware e software para ajudá-lo a fazer o melhor em seu trabalho, mas se você nunca se esforçar a mais, nunca será o melhor.
Todos nós entendemos, escrever documentação geralmente é uma droga … muito. Mas no final, vale a pena., Porque embora não seja o desenvolvedor do ano, uma boa documentação pode torná-lo um verdadeiro herói .
Algumas coisas que podem melhorar sua documentação
- Seja detalhado, mas direto ao ponto. A maioria das pessoas só quer saber o que isso faz, não é a história de vida desde a concepção.
- Aponte para arquivos importantes [scripts para download]. Se um script depende muito de um arquivo específico ou conjunto de arquivos, pode ser uma boa idéia mencionar esse arquivo em sua documentação.
- Organização é a chave. Separar as coisas em seções pode facilitar a absorção das informações. Além disso, isso pode facilitar a pesquisa de coisas.
- Use explicações simples. Ao tentar explicar qualquer coisa, finja que esta é apenas a segunda página da documentação que o leitor leu. Trate-os como se soubessem um pouco, mas não tudo.
- Use exemplos diretos. Os exemplos são uma parte importante de qualquer documentação, eles permitem que o leitor tenha uma noção aprofundada de como as coisas devem ser feitas. Ao escrever exemplos, tente minimizar o excesso de script. Muito script às vezes pode ser confuso.
Obrigado pela leitura
Se você gostou do que escrevi, considere aprovar este protocolo ou me endossar .
Se você quiser ver mais coisas minhas, pode ver outros protocolos que escrevi ou visitar meu perfil .