Pour moi, savoir construire une documentation est une des compétences les plus rares et précieuses chez les développeurs. C’est d’ailleurs pour moi un point critique de non-embauche chez les candidats juniors! Venir avec des projets qui n’ont strictement aucune documentation (markdown) n’est pas acceptable selon moi.
Pour un projet sur github par exemple :
- Quels sont les prérequis du projet ? (version de Node.js, base de données utilisée etc).
- A quel besoin le projet répond-t-il ?
- Des diagrammes sont t’ils disponibles pour pouvoir mieux comprendre l’architecture et les choix fait dans le projet / code ?
Donc pensez à bien documenter vos projets personnels car je pense que cela à un impact très important aussi bien pour les personnes techniques et non techniques (et je ne parle pas de faire un copier-coller d’un getting started). Perso je n'ai pas besoin de voir le code d’un développeur qui construit des documentations rigoureusement…
Exemple de projets pour vous inspirer: JS-X-Ray, SlimIO Config, Flydrive, Hooks.
- JSDoc (voir aussi ESDoc).
- TypeDoc (pour TypeScript)
- Github Pages
- What it takes to build great product documentation
- Beyond the README: Creating Effective Documentation for Your Project by Rand McKinney, IBM
Si vous construisez une API: avoir un OpenAPI avec par exemple une interface Swagger peut-être un gros plus (une collection postman peut aussi faire l’affaire).
⬅️ 🌇 Architecture & Paradigmes: JSON Schema | ➡️ 🌇 Architecture & Paradigmes: Clean code