Diese Präsentation wurde erfolgreich gemeldet.
Wir verwenden Ihre LinkedIn Profilangaben und Informationen zu Ihren Aktivitäten, um Anzeigen zu personalisieren und Ihnen relevantere Inhalte anzuzeigen. Sie können Ihre Anzeigeneinstellungen jederzeit ändern.

Pourquoi la documentation compte ?

2.083 Aufrufe

Veröffentlicht am

  • Als Erste(r) kommentieren

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

×