Pourquoi la
documentation
compte ?
Where Content
Means Business
Sarah ?
● Sarah Haïm-Lubczanski
● Previously développeuse PHP 
– Previously formatrice
● Previously développeuse PHP
Previ...
Agenda
● Pourquoi je suis devenue documentaliste ?
● Comment on écrit une bonne documentation ?
● Générer de la doc
● L'an...
4
eZ Systems & eZ Publish
4
Quelques mots sur eZ
Systems
eZ Systems en chiffres
 Fondé en 1999 à Skien en Norvège
 Présent dans 6 pays : France, Allemagne, 
Etat-Unis , Norvège,...
Quelques mots sur eZ Systems
 Créateur du système de gestion de contenu eZ 
Publish Platform 
 Leader sur le marché de l...
7
eZ Publish Platform 5.3
● Multi-sites
● Multi-langues
● Multi-canal
8
Documenter
8
Pourquoi je documente ?
● Aider les gens à comprendre
– Les concepts
– Les features
– Comment faire
– Les bonnes pratiques...
Je crois que la doc ça vend plus
● Décision d'achat
● Confiance : fraîcheur, pertinence
– Réputation
● Complément au disco...
Tout le monde peut améliorer sa documentation
● Nouvelle : http://confluence.ez.no
– Aucun lien depuis la homepage
● Ancie...
Gérer la doc existante et ancienne
● Documentation existante
– Ancienne version d'eZ Publish 4,x
– Version actuelle d'eZ P...
Janvier 2014 : Documentation v 5
Janvier 2014 : Documentation version 4.x
Documentation juin 2014
Pour qui vous documentez ?
● utilisateurs externes
● utilisateurs internes
● développeurs du futur
● concurrents
Personas à la rescousse
● Technique des personas
● Nous a permis d'identifier la doc manquante
● Doc Effort Week
– 4 collè...
Quand on est dev, on aime les scripts
Avantages
● Depuis le code
● Lisible pour ceux qui ne lisent
pas le code
Inconvénien...
Comment les dev eZ Publish écrivent la doc ?
● Doc = une colonne de notre Kanban Board
●
A quoi sert un Tech Writer ?
● Dev issues passent par la doc
– PR avec discussion
– Commentaires pour Team Doc
● La doc pe...
Qu'est-ce que je fais le plus souvent ?
● Tester des parties de la doc
● Lire
● Comprendre
● Organiser le contenu
● Commun...
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 ca...
Plusieurs manières d'organiser la documentation
● TOC (Table of Content)
● Task-based
– Contextuelle
● Guerilla documentat...
Problématiques de la doc technique
● Coloration syntaxique
– Plusieurs langages
● Outils existants et leur prix
● Workflow...
Que doit-on documenter ?
● Trouver les questions que les utilisateurs se posent
● Fréquenter les mêmes lieux
● A/B testing...
L’apport de la communauté opensource
● http://share.ez.no
● Sondage
– Sur les attentes
● Sur la création de contenu
– Coll...
Opensource et documentation
● Ce qu'on prévoit de faire à eZ Systems
– Utiliser un soft opensource pour la doc
● ReadTheDo...
Memento
● Mieux vaut une doc commencée qu'inexistante
– DO IT NOW !
● Mettez à jour
● Si vous ne la proposez pas, quelqu'u...
Merci !
Questions ?
sarah.haim@ez.no
Twitter @mereteresa
Where Content
Means Business
Pourquoi la documentation compte ?
Upcoming SlideShare
Loading in...5
×

Pourquoi la documentation compte ?

1,161

Published on

0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,161
On Slideshare
0
From Embeds
0
Number of Embeds
12
Actions
Shares
0
Downloads
4
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide
  • Thanks for having me here virtually. I really wish I could make it but this was not possible for different reasons - I am like Snowden but the other way round... I cant leave the US right now :-)
    I already look forward to #3 as there is no way I miss it!
    Here we go, a new release is round the corner, it’s time for eZ Publish 5.2 codename aconcagua
    South America, Argentina
    almost 7000 meters
    a bit more than two month to go
  • opensource
    Faire participer la communauté
    Quoi documenter ?
  • Ventoux
    Sprints = montagnes et le dernier sprint pre release était le ventoux
    Comme je suis cycliste, cela me touche.
  • Depuis la version 5.0
    Basé sur Symfony 2
    DemoBundle : contenu fictif pour comprendre l'implémentation des features
    => sorte de documentation par l'exemple
  • Qui aime faire de la doc ?
    Les docs existantes
    Personne ne veut le faire
    Mauvaise qualité de la doc
    DIY !
  • Aider les gens à utiliser ce que mes collègues développent
    Permettre à des visiteurs de comprendre
    L'objet du logiciel et ses concepts
    Les features
    Comment faire
    Les bonnes pratiques
    Pour l'entreprise
    Publicité
    Méta-information : santé et vivacité
  • Avant d’acheter je peux aller voir la doc, même si je n’y connais rien au technique
    Confiance dans le produit passe par la doc
    Doc en tant que support niveau de base
  • Etre clair sur les versions
    Cohérence graphique
    Organisationnelle
    Nos choix
    - bugfix only sur doc legacy
    - @todo : améliorer la recherche
  • Contenu de la page :
    - Blabla corpo
    - Peu de liens dans le menu
    - Couleurs sans relation avec le produit
  • Habitudes de navigation
    Manuel utilisateur pour la version 5
    Mais pas le manuel technique
  • Gros travail sur la homepage
    => Homepage plus claire
    - Accès à la doc legacy
    - Labels
    - Sujets mis en avant
    - Petite description du produit
  • Pour qui on documente ?
    utilisateurs externes (clients)
    utilisateurs internes (support)
    développeurs du futur (vous-même ou pas)
    concurrents
    Par exemple notre marketing a des personas mais ceux qui consultent la doc ne sont pas les personas du markeking
    Developpeur PHP débutant
    Développeur PHP expérimenté
    Intégrateur
    Administrateur système
  • Doc effort week :
    Juste après avoir envoyé la release à la QA
  • Inconvénients
    Pas d’information supplémentaire => par rapport à qqn qui lirait le code
    La regen régulièrement sans quoi : obsolète
    => tâche de maintenance supplémentaire à assurer (script ou regen manuelle)
    IDE peuvent se substituer à une doc contenant uniquement les arguments
  • Avantage colonne 
    - passage obligé
    - visibilité de la charge
    Inconvenient
    - partie bloquante
    - dev peut déléguer la partie doc
  • Tester des parties
    Installation du logiciel
    Affichage
    Ecrire
    des commentaires dans les issues
    Des pages de doc
    Faire des screenshots
    Lire
    Organiser le contenu
    Mettre des mots clefs
    Créer des points d' entrée
    Lier des pages
    Communiquer entre la QA et les dev
    Veille documentaire
    Comment font les autres ?
    Pourquoi ?
  • Canard en plastique : vulgariser
    Mots clefs :
    - méta info,
    - notions à ajouter,
    - liens
    Près du code : github pages
    Près du support : au même endroit sur le site, liens
    Près du marketing : mettre des liens vers la présentation des features (approche DSI)
  • TOC
    Task based
    Guerilla : ce que les gens font quand vous ne fournissez rien
    Attention aux commentaires (php.net) :
    - commentaires = interaction utilisateur
    - comm = vos pixels
    Contenu qualité ?
  • Coloration syntaxique
    Plusieurs langages
    Rendre clair les exemples
    Différencier les langages
    Outils existants et leur prix
    Nouvel outil = courbe d'apprentissage
    Workflow de dev
    Doc intégrée au workflow
    Chiffrer du temps pour la doc
    => c'est comme les tests
    Maintenance de la doc
    => ça prend du temps
    Equipe support
    Chacun a SA doc
  • Fréquenter les mêmes lieux (veille)
    Forums
    Stackoverflow
    IRC
    Twitter
    A/B testing
    Problèmes rencontrés
    Bugs, tips and tricks
    Livrer des fichiers de raccourcis
    Des confs de VM
    Doc près du fichier
    => Rejoint Lieu où placer la doc
  • Collaboration :
    - écrire
    - demander, critiqueLa critique est aisée mais l'art est difficile.
    - corriger
    - proposer de supprimer
  • Je n'ai pas parlé de
    - dette technique pour la doc
    - formats de sortie
    - offline edition
    - DRY doc
    - feedback
    - le code doit être du vrai
    - Reference séparée des guides (topics)
    Séparée de la FAQ
  • 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
    1. A particular slide catching your eye?

      Clipping is a handy way to collect important slides you want to go back to later.

    ×