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!

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

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