Développeurs, pourquoi ne pas ignorer la documentation

Dans le domaine du développement des applications mobiles, des applications Web, des applications de bureau ou des bibliothèques JavaScript, la documentation joue un rôle important qui pourrait déterminer le succès du développement du logiciel. Mais si vous avez déjà fait de la documentation, vous conviendrez avec moi que c'est à peu près ce que les développeurs préfèrent faire..

Contrairement à l'écriture de code (ce à quoi les développeurs se sont engagés), la documentation (ce que nous n'avons pas fait) doit et doit être facilement digérée par toutes les personnes. Techniquement, nous devons traduire un langage machine (code) dans un langage compréhensible pour les humains, qui est plus dur qu'il n'y paraît..

Bien que cela puisse être une lourde charge, la rédaction de la documentation est importante et apportera des avantages pour vos utilisateurs, vos collègues et surtout vous-même..

Une bonne documentation aide les utilisateurs

La documentation aide le lecteur comprendre le fonctionnement d'un code, évidemment. Mais de nombreux développeurs font l’erreur de supposer que les utilisateurs du logiciel seront compétents. Par conséquent, la documentation peut être un document mince, omettant beaucoup d’essentiels qu’elle aurait dû contenir depuis le début. Si vous maîtrisez la langue, vous pouvez résoudre le problème de votre propre initiative. si vous ne l'êtes pas, alors vous êtes perdu.

La documentation destinée aux utilisateurs consiste généralement en une utilisation pratique ou “comment”. La règle de base lors de la création de documentation pour les utilisateurs généraux est que il devrait être clair. L'utilisation de mots conviviaux est préférable aux termes techniques ou au jargon. Des exemples d'utilisation réelle seront également grandement appréciés.

Un bon schéma de présentation aiderait également les utilisateurs à parcourir chaque section de la documentation sans fatigue oculaire. Quelques bons exemples (alias mes favoris) sont la documentation pour Bootstrap et WordPress ' “Premiers pas avec WordPress”.

Cela aide également les autres développeurs

Chaque développeur aura son propre style de codage. Cependant, lorsqu'il s'agit de travailler en équipe, nous devons souvent partager les codes avec les autres coéquipiers. Il est donc essentiel de avoir un consensus sur une norme garder tout le monde sur la même page. Une documentation bien écrite serait la référence dont l'équipe a besoin

Mais contrairement à la documentation destinée aux utilisateurs finaux, cette documentation décrit généralement: procédures techniques comme la convention de nommage de code, montrant comment des pages particulières doivent être construites et comment l’API fonctionne avec les exemples de code. Souvent, nous devrions également écrire la documentation en ligne avec le code (connu sous le nom de commentaires) pour décrire ce que fait le code.

De plus, dans le cas où vous avez nouveaux membres rejoignant plus tard, cette documentation pourrait être un moyen efficace de former les membres de votre équipe. Vous n'avez donc pas à leur donner une analyse individuelle du code..

Étrangement, cela aide également le codeur

La chose amusante à propos du codage est que parfois même les développeurs eux-mêmes ne comprennent pas le code qu'ils ont écrit. Cela est particulièrement vrai dans les cas où les codes ont été laissés intacts pendant des mois voire des années.

Un besoin soudain de revoir les codes pour une raison ou une autre laisserait se demander ce qui se passait dans leur esprit quand ils ont écrit ces codes. Ne soyez pas surpris: j'ai déjà été dans cette situation. C'est précisément quand je souhaité J'avais bien documenté mon code.

En documentant vos codes, vous pourrez aller au fond de vos codes rapidement et sans frustration, ce qui vous permettra d’économiser beaucoup de temps qui peut être consacré à l’introduction des modifications..

Ce qui fait une bonne documentation?

Il y a plusieurs facteurs pour construire une bonne documentation.

1. Jamais supposer

Ne présumez pas que vos utilisateurs savent quoi vous savoir aussi bien que ils vouloir savoir. C'est toujours mieux pour commencer depuis le tout début quel que soit le niveau de compétence des utilisateurs.

Si vous avez construit un plugin jQuery, par exemple, vous pourrez vous inspirer de la documentation de SlickJS. Il montre comment structurer le HTML, où placer le CSS et le JavaScript, comment initialiser le plugin jQuery à son niveau le plus élémentaire, et montre même le balisage final complet après avoir ajouté tous ces éléments, ce qui est une évidence..

La ligne de fond est la documentation est écrite avec le processus de pensée d'un utilisateur, pas un développeur. Cette approche de votre propre documentation vous donnera une meilleure perspective pour organiser votre propre pièce..

2. Suivez la norme

En ajoutant une documentation qui va en ligne avec le code, utiliser le standard attendu de la langue. C'est toujours une bonne idée de décrire chaque fonction, les variables ainsi que la valeur renvoyée par la fonction. Voici un exemple de bonne documentation en ligne pour PHP.

 / ** * Ajoute des classes personnalisées au tableau de classes de corps. * * @param array $ classes Classes pour l'élément body. * @return array * / function body_classes ($ classes) // Ajoute une classe de blog de groupe aux blogs avec plus d'un auteur publié. if (is_multi_author ()) $ classes [] = 'blog-groupe';  retourne $ classes;  add_filter ('body_class', 'body_classes'); 

Vous trouverez ci-dessous quelques références sur la mise en forme de la documentation intégrée avec les meilleures pratiques en PHP, JavaScript et CSS:

• PHP: Standard de documentation PHP pour WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

Si vous utilisez SublimeText, je vous conseillerais d'installer DocBlockr pour pré-renseigner intelligemment votre code avec une documentation en ligne..

3. éléments graphiques

Utilisez des éléments graphiques, ils parlent mieux que le texte. Ces supports sont utiles, en particulier si vous construisez un logiciel avec une interface graphique. Vous pouvez ajouter des éléments de pointage tels que des flèches, un cercle ou tout ce qui peut aider les utilisateurs à déterminer où aller pour accomplir les étapes, sans conjecture.

Vous trouverez ci-dessous un exemple tiré de l'application Tower où vous pourrez vous inspirer. Ils expliquent efficacement le fonctionnement du contrôle de version, ce qui le rend plus compréhensible que l'utilisation de lignes de commande en texte brut..

4. sectionnement

Vous pouvez envisager de regrouper quelques éléments de la documentation dans des listes et des tableaux à puces, ce qui simplifie l'analyse et la lecture de contenu plus long pour les utilisateurs..

Ajoutez une table des matières et divisez la documentation en sections faciles à assimiler, en veillant toutefois à ce que chaque section reste pertinente par la suite. Gardez-le court et simple. Vous trouverez ci-dessous un exemple de documentation bien organisée sur Facebook. La table des matières nous emmène là où nous voulons aller en un clic.

5. Réviser et mettre à jour

Enfin, examinez la documentation pour déceler les erreurs et révisez-la si nécessaire ou chaque fois que des modifications importantes sont apportées au produit, au logiciel ou à la bibliothèque. Votre documentation ne serait d'aucune utilité si elle n'était pas régulièrement mise à jour parallèlement à votre produit.