DEV Community

Sarah Haïm-Lubczanski
Sarah Haïm-Lubczanski

Posted on • Edited on

Documentation style guide, you said?

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

Heroku

Simplify your DevOps and maximize your time.

Since 2007, Heroku has been the go-to platform for developers as it monitors uptime, performance, and infrastructure concerns, allowing you to focus on writing code.

Learn More

Top comments (0)

A Workflow Copilot. Tailored to You.

Pieces.app image

Our desktop app, with its intelligent copilot, streamlines coding by generating snippets, extracting code from screenshots, and accelerating problem-solving.

Read the docs