atoum & Documentation
entre traduction, mise à jour et utilisation
atoum's day 2016
Who is speaking?
- Jonathan Van Belle
- @Grummfy
- grummfy@atoum.org
- doc master de atoum
Documentation ?
-
Universels, tous les projets en ont besoin
-
Devrait être traduit
-
Rarement maintenu
-
Point d'entrée vers le projet
-
Pas de question, juste de la doc!
Historique
- mars 2012
- Gérald Croës
- Début
- Anglais
-
2012-2015
-
marmotz (Renaud LITTOLFF)
-
Anglais & français
-
crowdin
-
read the doc
-
Historique
- 2015
- Finalisation traduction
- 2016
- Template (agallou)
- Reformulation & reorganisation
- Nettoyage
- Remplissage des trous
- Rusty
- ...
Quelques chiffres
- 2 doc master
- contributeurs
- 29 depuis le début (vs 50 atoum)
- 7 depuis janvier (vs 9 atoum)
- 139 PR
- 71 issues donc 26 ouverte
Stack technique
- format reStructuredText
- texte
- choix des "level" (#, *, =, -, ", ^, `, :, ., ')
- plus complet que markdown
-
Sphinx
- génération multiple (pdf, epub, ... et html)
- docker de build (cf readme)
-
Rusty
- code d'exemple juste
- Crowdin
Traduction
-
Crowdin
- tokenization
- suggestion & aide à la traduction
- visualisation de ce qui manque
- traduction synchronisée avec le fichier
- Problème
- compliquer à maintenir
- impossible de changer la langue de référence
Read the doc
- Read the doc (aka RTD)
- Hébergeur
- Génération
- hook github
- Open source
- Améliorer par la communauté
Maintenance
- Correction
- Orthographe & grammaire (arghhhh)
- Syntaxe
- Traduction
- Ajout de nouvelle fonctionnalités
- Communication devellopeur - doc
- PR ou commit sur atoum => issue doc
Trucs & Astuces
- Importance du README!
- comme pour tout projet
- Génération en local
- docker
- check des erreurs
- Bien relire les PR
- Avoir un correcteur orthgraphique
- ou un humain faisant office de
Questions?
thanks
http://slides.com/grummfy/atoum-day-2016-documenation