Documentation

Documenter mon projet open-source rapidement
par

Documenter mon projet open-source rapidement

Je reçois beaucoup de questions sur les outils à utiliser. J’ai décidé d’y répondre ici.

Comment documenter de façon économique un projet open-source, fait sur le temps libre ?

Les générateurs statiques sont très efficaces, et en version hébergée pour vous, il n’y a pas, en 2020, tant de solutions que cela. Mes recherches ont été faciles.

En fait, j’ai identifié 4 solutions pratiques qui supportent le Markdown :

  • Github Pages : un Jekyll rattaché à vos projets hébergés sur Github
  • Gitlab Pages : à vous de choisir le générateur statique qui vous convient.
  • ReadTheDocs (gratuit pour les projets open-source) : choisissez entre deux parfums, un Sphinx ou un MkDocs, pour utiliser le format de fichier qui vous convient le mieux.
  • Gitbook (gratuit pour les projets open-source) : solution propre, l’équipe est à Lyon.
Publicité
par

[talk] Sans documentation, la fonctionnalité n’existe pas !

Voici la vidéo, les slides et surtout les liens complémentaires de la conférence que j’ai eu l’honneur d’animer au PHP Tour 2018 à Montpellier. J’avais intitulé ma session Sans documentation, la fonctionnalité n’existe pas ! et le titre avait déjà amené beaucoup de débats avec mes pairs. Je vous laisse donc m’écouter, me lire et, si le sujet vous intéresse, approfondir la question par vous-même.

La vidéo de la session

Les slides de « Sans documentation, la fonctionnalité n’existe pas »

J’ai pris soin de garder les animations, c’est pourquoi vous avez un grand nombre de diapos : quand il y a deux versions, c’est que j’ai gardé les versions avant et après l’animation.

Les liens complémentaires

Durant ma présentation, je cite des outils ou je référence le travail d’autres personnes, voici les liens complémentaires.

 

Mon interview dans le podcast Echo : gérer et maintenir une documentation

J’ai été interviewée par le podcast Echo, qui compte déjà 4 épisodes, lors du PHPTour à Montpellier, ce qui m’a donné l’opportunité de dire à haute voix ma vision de la documentation au quotidien. Si vous avez 7 minutes devant vous, c’est l’occasion d’écouter ma voix.

 

La Documentation comme une punition

L’autre matin encore, j’ai entendu mes collègues parler de leurs tâches possibles pour les prochaines heures, et l’un dire à l’autre : « Tu peux écrire la documentation de telle Story, si tu veux » et l’autre répondre : « Non, je ne suis pas désespéré à ce point. »

Mes collègues sont formidables et ils me donnent l’occasion de parler de cette tradition de voir la documentation de ses développements comme une punition. Évidemment, ce n’est pas la partie la plus sexy du code de se taper la Documentation. Evidemment, c’est pas l’fun de devoir expliquer ce qu’on a brillamment conçu avec son cerveau super-intelligent pour que d’autres péons puissent comprendre le fonctionnement, sinon l’intention de votre création.

Pillory (PSF)

Cloué au pilori, la punition

Simplement, si vous avez fait vos développements super-cools, qui va savoir les utiliser hormis vous ? Qui va savoir qu’ils existent si vous n’en faites aucune promotion ?

Pour moi, la documentation sert à plusieurs personnes :

  •  Le développeur qui est forcé d’expliquer et remettre à plat l’utilité et le fonctionnement de son oeuvre.
  • Les utilisateurs qui veulent s’en servir, qu’ils soient utilisateurs techniques ou non
  • Les autres collègues, incluant le développeur lui-même dans le futur, qui sont parfois forcés de reprendre le code de quelqu’un d’autre. On disait parfois en riant : « ça a été difficile à écrire, ça doit être difficile à lire », en réalité, c’est une blague, faut pas le faire.
  • La partie marketing qui peut ainsi affirmer que la fonctionnalité existe et qu’il est possible de s’en servir

Quand vous voyez la Documentation comme une punition, en réalisé, vous punissez les personnes que je cite dans ma courte liste. Et quand j’évoque la Documentation, cela ne se limite pas aux pages écrites dans un bon anglais/français, avec des jolis exemples théoriques de code. Cela inclut les bons messages d’erreurs, les informations retournées par l’API, et les commentaires dans le code, ainsi que les diagrammes concernant l’architecture et le pourquoi de ces choix.

Le CommitStrip m’y a refait penser au point que je me suis dit que j’allais écrire un billet sur le sujet : http://www.commitstrip.com/fr/2016/07/27/documentation-just-before-vacation/

Il est temps de réfléchir et mûrir un peu sur ce sujet, ne croyez-vous pas ?

 

2014 année de la doc

Actividades conmemorativas de las Instrucciones Año XIII 14

By Karin Porley von Bergen (Flickr: Instrucciones Año XIII) [CC-BY-SA-2.0], via Wikimedia Commons

Mon titre rime presque, n’est-ce pas ? Bon, le mot deux-mille quatorze ne rime apparemment avec rien dans la langue française.

Depuis janvier, j’ai changé de boulot. Non seulement j’ai changé d’employeur, mais surtout c’est mon poste qui a changé. J’étais développeuse PHP. Je suis Technical Writer chez eZ Systems. Vous les connaissez, si vous faites du PHP, c’est la société derrière le méga-CMS opensource eZ Publish. Pour le dire de manière basique : j’écris de la documentation. (1)

D’aucuns trouvent que la doc, c’est LE truc fastidieux du projet. Ecrire du texte pour expliquer aux utilisateurs ce qu’on a fait, c’est vraiment la corvée des développeurs, j’ai l’impression. J’ai au contraire envie de pousser la documentation comme quelque chose d’important sur un projet, surtout un projet opensource. Les utilisateurs sont quand même ceux qui donnent la vie à votre logiciel, et ceux qui font votre réputation. Ils ont besoin de savoir comment se servir de votre logiciel.

(1) En fait, bien entendu, c’est un peu plus élaboré, puisqu’actuellement, le site Doc.ez.no concerne la documentation de l’avant-dernière version 4 et que la dernière version 5 de la documentation est sur Confluence.ez.no. Mon rôle est que cela soit clair de trouver les informations dont vous avez besoin dans la documentation, sans avoir à chercher. Entre les documentations à rédiger qui m’attendaient dès que mon arrivée a été prévue et les nouveaux développements de mes collègues, en plus de lire la documentation existante et d’apprendre, je ne m’ennuie pas.