Suite à l'article (en 2 parties) sur comment structurer une documentation technique, j'ai remarqué qu'il manquait la partie Style Guide.
Un Style Guide, c'est l'équivalent de PSR-12 pour PHP ou des PEP 8 pour Python, l'idée est de guider la personne qui rédige la documentation, pour lui faciliter le travail.
Par exemple, faut-il écrire en français, ou en anglais ? Au présent ou au passé ? Tutoyer ou vouvoyer, ou même éviter l'adresse au lecteur-ice ?
Est-ce que le mot correct est backend, back-end ou back end ?
Si tous ces détails vous semblent pertinents pour améliorer la qualité de votre documentation (que les docs soient homogènes, notamment), il vous faut un Style Guide de doc.
Pour trouver un Style Guide existant à suivre (par exemple, celui de Google Developers), voici une ressource intéressante :
https://www.writethedocs.org/guide/writing/style-guides/#how-to-articles-for-writing-a-style-guide
Top comments (0)