Desenvolvedores Por que você não deveria ignorar a documentação

Na área de desenvolvimento de aplicativos móveis, aplicativos da Web, aplicativos de área de trabalho ou bibliotecas JavaScript, a documentação desempenha um papel importante que pode determinar o sucesso do desenvolvimento do software. Mas se você já fez documentação, você concorda comigo que é praticamente a coisa menos favorita dos desenvolvedores.

Ao contrário de escrever código (que é o que os desenvolvedores se inscreveram para fazer), a documentação (que nós não fizemos) deve e deve ser facilmente digerida por todos. Tecnicamente, temos que traduzir uma linguagem de máquina (código) em uma linguagem que seja compreensível para os seres humanos, o que é mais difícil do que parece.

Embora possa ser muito oneroso, escrever a documentação é importante e oferecerá vantagens para seus usuários, seus colegas e especialmente para você..

Boa documentação ajuda os usuários

Documentação ajuda o leitor entender como funciona um código, obviamente. Mas muitos desenvolvedores cometem o erro de assumir que os usuários do software serão proficientes. Assim, a documentação pode ser um material fino, ignorando muito do essencial que deveria ter contido desde o início. Se você é experiente no idioma, pode descobrir as coisas por sua própria iniciativa; se você não é, então você está perdido.

A documentação destinada aos usuários geralmente consiste em uso prático ou “como”. A regra prática ao criar documentação para usuários em geral é que deve ser claro. Usar palavras amigáveis ao homem é preferível a termos técnicos ou jargões. Exemplos de uso real também serão muito apreciados.

Um bom design de layout também ajudaria os usuários a examinar cada seção da documentação sem cansaço visual. Alguns bons exemplos (também conhecidos como meus favoritos) são documentação para Bootstrap e WordPress ' “Primeiros passos com o WordPress”.

Também ajuda outros desenvolvedores

Cada desenvolvedor terá seu próprio estilo de codificação. Mas, quando se trata de trabalhar em equipe, muitas vezes temos que compartilhar códigos com os outros companheiros de equipe. Por isso, é essencial ter um consenso sobre um padrão para manter todos na mesma página. Uma documentação devidamente escrita seria a referência que a equipe precisa

Mas, ao contrário da documentação do usuário final, esta documentação geralmente descreve procedimentos técnicos como a convenção de nomenclatura de código, mostrando como determinadas páginas devem ser construídas e como a API funciona junto com os exemplos de código. Muitas vezes também teríamos que escrever a documentação em linha com o código (conhecido como comentários) para descrever o que o código está fazendo.

Além disso, no caso em que você tem novos membros se juntando sua equipe mais tarde, esta documentação pode ser uma maneira eficaz de treiná-los, então você não precisa dar a eles uma revisão 1-on-1 sobre o código.

Estranhamente também ajuda o codificador

O engraçado da codificação é que às vezes mesmo os próprios desenvolvedores não compreendem o código que eles escreveram. Isso é particularmente verdadeiro nos casos em que os códigos foram deixados intocados por meses ou até anos..

Uma necessidade repentina de revisitar os códigos por uma razão ou outra deixaria alguém imaginando o que se passava em suas mentes quando escreviam esses códigos. Não fique surpreso: já estive nessa situação antes. Isto é precisamente quando eu desejou Eu tinha documentado meu código corretamente.

Ao documentar seus códigos, você conseguirá chegar ao final de seus códigos rapidamente e sem frustração, poupando muito do seu tempo que pode ser gasto na obtenção das alterações..

O que faz para uma boa documentação?

Existem vários fatores para construir uma boa documentação.

1. Nunca assuma

Não presuma que seus usuários saibam o que você sabe bem como o que eles quer saber. É sempre melhor para começar desde o começo independentemente do nível de proficiência dos usuários.

Se você construiu um plugin jQuery, por exemplo, você pode se inspirar na documentação do SlickJS. Ele mostra como estruturar o HTML, onde colocar o CSS e o JavaScript, como inicializar o plugin jQuery em seu nível mais básico, e até mesmo mostrar a marcação final completa após adicionar todas essas coisas, o que é algo óbvio.

A linha inferior é a documentação é escrita com o processo de pensamento de um usuário, não um desenvolvedor. Aproximando-se de sua documentação, você terá uma perspectiva melhor ao organizar sua própria peça.

2. Siga o padrão

Adicionando documentação que está alinhada com o código, usar o padrão esperado do idioma. É sempre uma boa ideia descrever cada função, as variáveis, bem como o valor retornado pela função. Aqui está um exemplo de boa documentação inline para PHP.

 / ** * Adiciona classes personalizadas à matriz de classes de corpo. * * @param array $ classes Classes para o elemento body. * @return array * / function body_classes ($ classes) // Adiciona uma classe de grupo-blog a blogs com mais de 1 autor publicado. if (is_multi_author ()) $ classes [] = 'group-blog';  retornar $ classes;  add_filter ('body_class', 'body_classes');

A seguir estão algumas referências para formatar a documentação em linha com as melhores práticas em PHP, JavaScript e CSS:

PHP: PHP Documentation Standard para WordPress
JavaScript: UseJSDoc
CSS: CSSDoc

Se você estiver usando o SublimeText, sugiro instalar o DocBlockr que pré-preencherá seu código com documentação em linha..

3. Elementos Gráficos

Use elementos gráficos, eles falam melhor que texto. Essas mídias são úteis, especialmente se você criar um software com interface gráfica. Você pode adicionar elementos apontadores como setas, círculo ou qualquer coisa que possa ajudar os usuários a descobrir aonde ir para realizar as etapas, sem adivinhações.

A seguir, um exemplo do aplicativo Tower, do qual você pode se inspirar. Eles explicam de forma eficiente como o controle de versão funciona de maneira agradável, o que o torna mais compreensível do que usar linhas de comando de texto simples.

4. Seccionamento

Você pode considerar envolver algumas coisas na documentação em listas e tabelas com marcadores, pois isso facilita a leitura e a leitura de conteúdo mais longo para os usuários.

Adicione uma tabela de conteúdo e divida a documentação em seções facilmente digeríveis, mantendo, no entanto, cada seção relevante com o que vem a seguir. Mantenha-o curto e direto. Abaixo está um exemplo de documentação bem organizada no Facebook. O índice nos leva para onde queremos ir em um clique.

5. Revise e Atualize

Por fim, revise a documentação em busca de erros e revise quando necessário ou sempre que houver alterações significativas no produto, no software ou na biblioteca. Sua documentação não seria útil para ninguém se não fosse regularmente atualizada junto com seu produto.