Les programmeurs devraient-ils accorder de l'attention à la rédaction de documentation ? C'est une question apparemment mineure, mais plutôt importante. En plus des programmes et des données, un logiciel comprend aussi de la documentation. De plus, si un programmeur ne sait qu'écrire des programmes et ne peut pas décrire ses idées de manière appropriée et élégante dans la documentation, alors il devient vraiment un « paysan du code ».

L'importance de rédiger de la documentation

Dans les secteurs liés au logiciel, que ce soit à l'école ou sur le lieu de travail, tout le monde a peut-être remarqué qu'en plus d'écrire des programmes et de dessiner des schémas de conception,il y a une autre tâche importante : rédiger de la documentationPourquoi rédiger de la documentation ? Parce que nous devons montrer ce que nous avons fait — non seulement à nos pairs, mais aussi au personnel d'autres postes, et même aux utilisateurs. Si nous ne savons qu'écrire des programmes et ne pouvons pas décrire nos idées de manière appropriée et élégante dans la documentation, alors nous devenons vraiment des « paysans du code ».

J'ai remarqué que très peu de collègues autour de moi savent rédiger une documentation de haute qualité. M. Kai-Fu Lee, dans lapréface de « The Wave »,a déclaré : « Je connais de nombreux ingénieurs de premier ordre, mais les ingénieurs excellents dotés de solides compétences narratives sont, parmi ceux que je connais, extrêmement rares. »

En effet, parmi les collègues que je connais, très peu savent exprimer clairement leurs idées dans la documentation.

1. Nous envoyons et recevons de nombreux courriels chaque jour. J'ai examiné attentivement et j'ai constaté que le contenu de nombreux courriels comportait soit des phrases maladroites, soit de nombreuses fautes de frappe, soit une ponctuation mal utilisée ou omise. Bien souvent, un courriel peut être interprété de nombreuses façons différentes, ce qui rend peu clair ce qu'il cherche vraiment à exprimer et réduit considérablement l'efficacité au travail.
2. En plus du code, les projets contiennent aussi une grande quantité de documentation. Quand j’ouvre la plupart des documents, la première chose que je ressens est :Une mise en page désordonnée, un formatage incorrect, des phrases maladroites et des fautes de frappe partout.Au premier coup d’œil, on voit que l’auteur n’a pas pris le document au sérieux, et sa capacité à exprimer et organiser ses phrases est également faible.
3. Lors des discussions d’équipe de projet, presque tout le monde parle de la manière d’écrire de bons programmes, mais personne ne mentionne comment améliorer la rédaction de documentation. Tout le monde semble convenir que le devoir d’un développeur est de bien écrire des programmes, et que tout le reste est secondaire.

La définition traditionnelle du logiciel informatique est la suivante : un logiciel est l’autre partie d’un système informatique qui est interdépendante du matériel. Un logiciel comprend l’ensemble complet des programmes, des données et de la documentation associée.Notez qu’il est ici question de « documentation associée ». Si la documentation n’est pas bien rédigée, le logiciel ne peut pas être considéré comme excellent. En fait, il existe des cas où les fonctions logicielles sont correctes, mais où des défaillances surviennent en raison de problèmes de documentation.

De manière générale, dans le processus de développement logiciel, les principaux documents impliqués aux différentes étapes sont présentés dans la figure suivante :

On peut voir que différents documents doivent être rédigés à différentes étapes du logiciel. À l'étape de planification, il faut rédiger des documents de conception détaillée, des documents de plan de tests unitaires et des documents de plan de tests d'intégration ; à l'étape de développement, ces mêmes documents sont encore nécessaires, mais sous forme de versions révisées, car lors du développement réel, nous pouvons découvrir des parties déraisonnables ou mal pensées de la conception précédente, ce qui nécessite de modifier les documents antérieurs ; à l'étape de test, il faut rédiger des rapports de tests unitaires, des rapports de tests d'intégration et des rapports de tests système ; à l'étape de publication du logiciel, il faut rédiger des manuels d'installation, des manuels utilisateur, des guides de mise à niveau, etc. Ces documents s'adressent principalement au personnel de support sur le terrain et aux utilisateurs, ils doivent donc être rédigés de manière facile à comprendre, et il ne doit y avoir aucune ambiguïté ; sinon, vous ne pouvez qu'attendre les plaintes des utilisateurs.

Pour rédiger une bonne documentation, nous devons d'abord corriger une idée fausse : celle selon laquelle la documentation n'est pas importante. La documentation doit être placée sur un pied d'égalité avec les programmes.

Comment rédiger une documentation de haute qualité ?

Ainsi, comment pouvons-nous rédiger une documentation de haute qualité ? Je pense que nous pouvons commencer par les aspects suivants :

1. Changez l'idée selon laquelle la documentation est secondaire. Dans le travail quotidien, prenez au sérieux chaque document que vous rédigez.
2. Pour les e-mails, exprimez avec précision ce que vous voulez dire. Avant d'envoyer un e-mail, vérifiez si le contenu est complet, s'il y a des fautes de frappe et si les phrases sont fluides.
3. Lorsque vous rédigez des documents, suivez strictement le modèle spécifié par l'équipe de projet. Après avoir terminé le document, lancez une vérification grammaticale pour corriger les fautes de frappe et les erreurs grammaticales. En règle générale, les phrases comportant des erreurs grammaticales sont soulignées par une ligne ondulée verte. Avant de soumettre le document, relisez l'intégralité du document pour voir s'il y a des omissions ou des lacunes.
4. Pendant votre temps libre, vous pouvez lire des livres ou des articles qui améliorent l'expression linguistique et les compétences rédactionnelles, et voir comment les autres expriment clairement leurs pensées. Par exemple, lire régulièrement les billets de blog d'excellents blogueurs sur CSDN est un bon moyen d'améliorer votre capacité d'écriture.

En général, comme pour d'autres activités, la rédaction de documentation reflète aussi l'attitude d'une personne. Rédiger une documentation de haute qualité peut non seulement améliorer votre image personnelle (si vous lisez un bon document, n'auriez-vous pas aussi une meilleure opinion de son auteur ?), mais aussi renforcer l'image du produit dans l'esprit des clients. Avec une telle analyse, il est vraiment nécessaire de consacrer plus d'efforts à la rédaction de la documentation.

Pour bien faire quelque chose, nous devons travailler dur sur tous les aspects. Dans le processus de développement logiciel, écrire du bon code est important, et exprimer clairement ses pensées dans la documentation l'est tout autant. « Code » et « documentation » sont comme les bras gauche et droit d'une personne ; les deux doivent se développer de manière équilibrée, et nous ne pouvons pas nous concentrer sur un seul.

De :CSDNAuteur : Zhou Zhaoxiong