Valorisez votre documentation

Conseils pratiques pour documentation (Sphinx) de projets (Python).

Lightning-talk pour DjangoCon-Toulouse 2012, par Benoît Bryon.


Présentation disponible sur http://tech.novapost.fr

Presenter Notes

La doc, c'est important

  • visibilité VS projet perso
  • maturité VS méfiance
  • pérennité VS fragilité du projet
  • utile pour une équipe VS inutile pour les héros

Presenter Notes

Le challenge

Outils, conventions et bonnes pratiques :

  • pour le code : nombre + notoriété
  • pour la documentation : pas grand chose ?

=> collecte d'expériences (succès et échecs)

=> vision commune sur la documentation

=> outils concrets

Presenter Notes

Écrivez le moins de doc possible

  • Générer du contenu : docstrings, manpages...
  • Chasser l'obsolescence :
    • doc externe => liens
    • procédures d'installation => scripts
    • architecture => configuration

Presenter Notes

Que mettre dans la doc ?

  • Exemples, documentation narrative
    => doctests !
  • Informations sur le projet (/about/)
    => .. include:: README, AUTHORS, LICENSE
  • Guide du contributeur, conventions
    => feedback over convention !

Presenter Notes

Une doc efficace

  • Canaliser les flux d'information
  • Feedback-driven
  • Support-driven

=> D'autres astuces sur http://docness.readthedocs.org

Presenter Notes

Contribuez !

Presenter Notes