1. Pourquoi la
documentation
compte ?
Where Content
Means Business

2. Sarah ?
● Sarah Haïm-Lubczanski
● Previously développeuse PHP
– Previously formatrice
● Previously développeuse PHP
Previously investie dans l'AFUP, puis dans l'AFUP Lyon
● Now ?
– Technical Writer at eZ Systems
● Depuis janvier 2014
– <sarah.haim@ez.no>
– Mon lieu de travail : http://doc.ez.no

3. Agenda
● Pourquoi je suis devenue documentaliste ?
● Comment on écrit une bonne documentation ?
● Générer de la doc
● L'ancien et le nouveau
● Ecrire la doc : protips
● Particularités opensource
● Points d'amélioration chez eZ Systems

4. 4
eZ Systems & eZ Publish
4
Quelques mots sur eZ
Systems

5. eZ Systems en chiffres
 Fondé en 1999 à Skien en Norvège
 Présent dans 6 pays : France, Allemagne,
Etat-Unis , Norvège, Japon, Pologne,
 15 ans d’expérience dans l’écosystème Open
Source
 Plus de 15 000 clients présents dans 120
pays
 Un Ecosystème de plus de 44 000 membres
et de 350 partenaires

6. Quelques mots sur eZ Systems
 Créateur du système de gestion de contenu eZ
Publish Platform
 Leader sur le marché de l’Enterprise Open
Source Content Management
 Nous accompagnons les sociétés dans leur
transition vers le digital en transformant leur
contenu en business digital rentable
@ezsystems | http://ez.no

7. 7
eZ Publish Platform 5.3
● Multi-sites
● Multi-langues
● Multi-canal

8. 8
Documenter
8

9. Pourquoi je documente ?
● Aider les gens à comprendre
– Les concepts
– Les features
– Comment faire
– Les bonnes pratiques
● Pour l'entreprise
– Publicité
– Méta-information

10. Je crois que la doc ça vend plus
● Décision d'achat
● Confiance : fraîcheur, pertinence
– Réputation
● Complément au discours commercial
● Support technique

11. Tout le monde peut améliorer sa documentation
● Nouvelle : http://confluence.ez.no
– Aucun lien depuis la homepage
● Ancienne : http://doc.ez.no
– Habitude
– Référencement

12. Gérer la doc existante et ancienne
● Documentation existante
– Ancienne version d'eZ Publish 4,x
– Version actuelle d'eZ Publish 5.3
● Choix possibles :
– Archiver la doc, figer
– Continuer à mettre à jour
– Rendre + trouvable
– Mettre des liens
● Problème des versions

13. Janvier 2014 : Documentation v 5

14. Janvier 2014 : Documentation version 4.x

15. Documentation juin 2014

16. Pour qui vous documentez ?
● utilisateurs externes
● utilisateurs internes
● développeurs du futur
● concurrents

17. Personas à la rescousse
● Technique des personas
● Nous a permis d'identifier la doc manquante
● Doc Effort Week
– 4 collègues
– 22 pages crées
– 172 mise à jour

18. Quand on est dev, on aime les scripts
Avantages
● Depuis le code
● Lisible pour ceux qui ne lisent
pas le code
Inconvénients
● Doublon de contenu
● Maintenance supplémentaire
● Inutile avec IDE
● Générer de la documentation depuis la PhpDoc ?
– Insuffisant

19. Comment les dev eZ Publish écrivent la doc ?
● Doc = une colonne de notre Kanban Board
●

20. A quoi sert un Tech Writer ?
● Dev issues passent par la doc
– PR avec discussion
– Commentaires pour Team Doc
● La doc peut corriger des problèmes

22. Qu'est-ce que je fais le plus souvent ?
● Tester des parties de la doc
● Lire
● Comprendre
● Organiser le contenu
● Communiquer
● Ecrire
● Veille documentaire
– Comment font les autres ?
– Pourquoi ?

23. Comment les dévs peuvent écrire de la doc sans douleur
● Ecrire la doc immédiatement après la fin du dév
● Technique du canard en plastique
● Penser aux mots-clefs
● Plusieurs manières d'organiser la doc
– Près du code
– Près du support
– Près du marketing
● Publish often !

24. Plusieurs manières d'organiser la documentation
● TOC (Table of Content)
● Task-based
– Contextuelle
● Guerilla documentation
– Forums
– Non controlable
● Search: notions clefs, tags
● Garder à l'esprit
– Visiteurs cherchent à résoudre problème
– En colère parfois

25. Problématiques de la doc technique
● Coloration syntaxique
– Plusieurs langages
● Outils existants et leur prix
● Workflow de dev
– Backlog
– Product Manager
● Maintenance de la doc
– Comme le code !
● Equipe support
● Chacun a SA doc

26. Que doit-on documenter ?
● Trouver les questions que les utilisateurs se posent
● Fréquenter les mêmes lieux
● A/B testing
● Bugs, tips and tricks

27. L’apport de la communauté opensource
● http://share.ez.no
● Sondage
– Sur les attentes
● Sur la création de contenu
– Collaboration
– Commentaires
● Si tu ne contribues pas
au code,
tu peux contribuer à la doc

28. Opensource et documentation
● Ce qu'on prévoit de faire à eZ Systems
– Utiliser un soft opensource pour la doc
● ReadTheDocs
● eZ Publish Platform
– Augmenter la facilité de collaboration
● Générer la documentation depuis des fichiers éditables
– Symfony-like
● Ranger la doc technique près du code
– Augmenter les reviews
– PR avec de la doc

29. Memento
● Mieux vaut une doc commencée qu'inexistante
– DO IT NOW !
● Mettez à jour
● Si vous ne la proposez pas, quelqu'un en fera une
● Tout le monde est concerné
● When in doubt, document !

30. Merci !
Questions ?
sarah.haim@ez.no
Twitter @mereteresa
Where Content
Means Business