Pourquoi la documentation compte ?

2 006 vues

Publié le

  • Soyez le premier à commenter

Pourquoi la documentation compte ?

  1. 1. Pourquoi la documentation compte ? Where Content Means Business
  2. 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. 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. 4 eZ Systems & eZ Publish 4 Quelques mots sur eZ Systems
  5. 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. 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. 7 eZ Publish Platform 5.3 ● Multi-sites ● Multi-langues ● Multi-canal
  8. 8. 8 Documenter 8
  9. 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. 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. 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. 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. 13. Janvier 2014 : Documentation v 5
  14. 14. Janvier 2014 : Documentation version 4.x
  15. 15. Documentation juin 2014
  16. 16. Pour qui vous documentez ? ● utilisateurs externes ● utilisateurs internes ● développeurs du futur ● concurrents
  17. 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. 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. 19. Comment les dev eZ Publish écrivent la doc ? ● Doc = une colonne de notre Kanban Board ●
  20. 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
  21. 21. 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 ?
  22. 22. 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 !
  23. 23. 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
  24. 24. 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
  25. 25. 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
  26. 26. 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
  27. 27. 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
  28. 28. 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 !
  29. 29. Merci ! Questions ? sarah.haim@ez.no Twitter @mereteresa Where Content Means Business

×