larlet-fr-david/david/2021/sources/2021-09-09 - Documentation.md

Documentation

[en] Here are six requirements that I have on a project for it to reach my gold approval for stellar docs.

1. Your docs belong in the code repository
2. Your docs is not extracted from code
3. Your docs features examples
4. You document every API call you provide
5. Your docs is easily accessible and browsed
6. Your docs should be ==easy to contribute to==

*Making world-class docs takes effort* (cache)

J’ai mis en place un document collaboratif dernièrement en prenant pour acquis que le markdown était lisible et éditable. C’était une grossière erreur. Même avec l’aide de hackmd, un document contenant principalement des liens est interprété comme étant trop technique pour être accessible à des personnes n’ayant pas cette habitude.

Un bon rappel que la route est encore très longue… (cache)