SlideShare une entreprise Scribd logo
Pourquoi la
documentation
compte ?
Where Content
Means Business
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
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
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,  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
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
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
● Pour l'entreprise
– Publicité
– Méta-information
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
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
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
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ègues
– 22 pages crées
– 172 mise à jour
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
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 peut corriger des problèmes
Pourquoi la documentation compte ?
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 ?
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 !
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
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
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
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
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
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 !
Merci !
Questions ?
sarah.haim@ez.no
Twitter @mereteresa
Where Content
Means Business

Contenu connexe

En vedette

eZ publish - Publication instantanée et fort trafic web
eZ publish - Publication instantanée et fort trafic webeZ publish - Publication instantanée et fort trafic web
eZ publish - Publication instantanée et fort trafic web
Gauthier Garnier
 
Présentation eZ Publish - PHP Québec
Présentation eZ Publish - PHP QuébecPrésentation eZ Publish - PHP Québec
Présentation eZ Publish - PHP Québec
Gauthier Garnier
 
Présentation générale eZ Publish
Présentation générale eZ PublishPrésentation générale eZ Publish
Présentation générale eZ Publish
Gauthier Garnier
 
Utilisation d’eZ Flow sur le site www.kaliop.fr
Utilisation d’eZ Flow sur le site www.kaliop.frUtilisation d’eZ Flow sur le site www.kaliop.fr
Utilisation d’eZ Flow sur le site www.kaliop.fr
Kaliop-slide
 
Réutilisabilité du code PHP
Réutilisabilité du code PHPRéutilisabilité du code PHP
Réutilisabilité du code PHP
Nicolas Le Nardou
 
Monitoring d'applications/environnements PHP : APM et Pinba
Monitoring d'applications/environnements PHP : APM et PinbaMonitoring d'applications/environnements PHP : APM et Pinba
Monitoring d'applications/environnements PHP : APM et Pinba
Idaf_1er
 
Présentation EZ Systems
Présentation EZ SystemsPrésentation EZ Systems
Présentation EZ Systems
VeilleMag
 
EZ Systems - EZ publish, la plate-forme de gestion de contenu web de nouvell...
EZ Systems -  EZ publish, la plate-forme de gestion de contenu web de nouvell...EZ Systems -  EZ publish, la plate-forme de gestion de contenu web de nouvell...
EZ Systems - EZ publish, la plate-forme de gestion de contenu web de nouvell...
Documation Gestion de l'information et du document numérique en entreprise
 
5 idées pour transformer votre contenu en business
5 idées pour transformer votre contenu en business5 idées pour transformer votre contenu en business
5 idées pour transformer votre contenu en business
eZ Publish Community
 
Livre blanc Smile - Le meilleur des CMS open source
Livre blanc Smile - Le meilleur des CMS open sourceLivre blanc Smile - Le meilleur des CMS open source
Livre blanc Smile - Le meilleur des CMS open source
Nicolas Bariteau
 
Matinale eZ Publish : la personnalisation dynamique
Matinale eZ Publish : la personnalisation dynamiqueMatinale eZ Publish : la personnalisation dynamique
Matinale eZ Publish : la personnalisation dynamique
Softeam Agency
 
Soirée Qualité Logicielle avec Sonar
Soirée Qualité Logicielle avec SonarSoirée Qualité Logicielle avec Sonar
Soirée Qualité Logicielle avec Sonar
ElsassJUG
 
Connecteur eZ Publish/ Magento
Connecteur eZ Publish/ MagentoConnecteur eZ Publish/ Magento
Connecteur eZ Publish/ Magento
Interakting
 
Réalisation d’une plateforme e-commerce de vente de prestations HTML dotée d...
Réalisation d’une plateforme e-commerce de vente de  prestations HTML dotée d...Réalisation d’une plateforme e-commerce de vente de  prestations HTML dotée d...
Réalisation d’une plateforme e-commerce de vente de prestations HTML dotée d...
kadzaki
 
Webinar : ezpublish pour vos projets e-tourisme
Webinar : ezpublish pour vos projets e-tourismeWebinar : ezpublish pour vos projets e-tourisme
Webinar : ezpublish pour vos projets e-tourisme
Kaliop-slide
 
Webinar e-tourisme : Créer une expérience utilisateur riche grâce à eZ Publish
Webinar e-tourisme : Créer une expérience utilisateur riche grâce à eZ PublishWebinar e-tourisme : Créer une expérience utilisateur riche grâce à eZ Publish
Webinar e-tourisme : Créer une expérience utilisateur riche grâce à eZ Publish
Kaliop-slide
 
Ezpublish
EzpublishEzpublish
Ezpublish
Core-Techs
 
Faire De l'Ecommerce Avec Des Solutions Open Source
Faire De l'Ecommerce Avec Des Solutions Open SourceFaire De l'Ecommerce Avec Des Solutions Open Source
Faire De l'Ecommerce Avec Des Solutions Open Source
Core-Techs
 
How to deploy & optimize eZ Publish
How to deploy & optimize eZ PublishHow to deploy & optimize eZ Publish
How to deploy & optimize eZ Publish
Kaliop-slide
 

En vedette (20)

eZ publish - Publication instantanée et fort trafic web
eZ publish - Publication instantanée et fort trafic webeZ publish - Publication instantanée et fort trafic web
eZ publish - Publication instantanée et fort trafic web
 
Ezpub formation-ezpublish
Ezpub formation-ezpublishEzpub formation-ezpublish
Ezpub formation-ezpublish
 
Présentation eZ Publish - PHP Québec
Présentation eZ Publish - PHP QuébecPrésentation eZ Publish - PHP Québec
Présentation eZ Publish - PHP Québec
 
Présentation générale eZ Publish
Présentation générale eZ PublishPrésentation générale eZ Publish
Présentation générale eZ Publish
 
Utilisation d’eZ Flow sur le site www.kaliop.fr
Utilisation d’eZ Flow sur le site www.kaliop.frUtilisation d’eZ Flow sur le site www.kaliop.fr
Utilisation d’eZ Flow sur le site www.kaliop.fr
 
Réutilisabilité du code PHP
Réutilisabilité du code PHPRéutilisabilité du code PHP
Réutilisabilité du code PHP
 
Monitoring d'applications/environnements PHP : APM et Pinba
Monitoring d'applications/environnements PHP : APM et PinbaMonitoring d'applications/environnements PHP : APM et Pinba
Monitoring d'applications/environnements PHP : APM et Pinba
 
Présentation EZ Systems
Présentation EZ SystemsPrésentation EZ Systems
Présentation EZ Systems
 
EZ Systems - EZ publish, la plate-forme de gestion de contenu web de nouvell...
EZ Systems -  EZ publish, la plate-forme de gestion de contenu web de nouvell...EZ Systems -  EZ publish, la plate-forme de gestion de contenu web de nouvell...
EZ Systems - EZ publish, la plate-forme de gestion de contenu web de nouvell...
 
5 idées pour transformer votre contenu en business
5 idées pour transformer votre contenu en business5 idées pour transformer votre contenu en business
5 idées pour transformer votre contenu en business
 
Livre blanc Smile - Le meilleur des CMS open source
Livre blanc Smile - Le meilleur des CMS open sourceLivre blanc Smile - Le meilleur des CMS open source
Livre blanc Smile - Le meilleur des CMS open source
 
Matinale eZ Publish : la personnalisation dynamique
Matinale eZ Publish : la personnalisation dynamiqueMatinale eZ Publish : la personnalisation dynamique
Matinale eZ Publish : la personnalisation dynamique
 
Soirée Qualité Logicielle avec Sonar
Soirée Qualité Logicielle avec SonarSoirée Qualité Logicielle avec Sonar
Soirée Qualité Logicielle avec Sonar
 
Connecteur eZ Publish/ Magento
Connecteur eZ Publish/ MagentoConnecteur eZ Publish/ Magento
Connecteur eZ Publish/ Magento
 
Réalisation d’une plateforme e-commerce de vente de prestations HTML dotée d...
Réalisation d’une plateforme e-commerce de vente de  prestations HTML dotée d...Réalisation d’une plateforme e-commerce de vente de  prestations HTML dotée d...
Réalisation d’une plateforme e-commerce de vente de prestations HTML dotée d...
 
Webinar : ezpublish pour vos projets e-tourisme
Webinar : ezpublish pour vos projets e-tourismeWebinar : ezpublish pour vos projets e-tourisme
Webinar : ezpublish pour vos projets e-tourisme
 
Webinar e-tourisme : Créer une expérience utilisateur riche grâce à eZ Publish
Webinar e-tourisme : Créer une expérience utilisateur riche grâce à eZ PublishWebinar e-tourisme : Créer une expérience utilisateur riche grâce à eZ Publish
Webinar e-tourisme : Créer une expérience utilisateur riche grâce à eZ Publish
 
Ezpublish
EzpublishEzpublish
Ezpublish
 
Faire De l'Ecommerce Avec Des Solutions Open Source
Faire De l'Ecommerce Avec Des Solutions Open SourceFaire De l'Ecommerce Avec Des Solutions Open Source
Faire De l'Ecommerce Avec Des Solutions Open Source
 
How to deploy & optimize eZ Publish
How to deploy & optimize eZ PublishHow to deploy & optimize eZ Publish
How to deploy & optimize eZ Publish
 

Similaire à Pourquoi la documentation compte ?

Bonnes pratiques de developpement en PHP
Bonnes pratiques de developpement en PHPBonnes pratiques de developpement en PHP
Bonnes pratiques de developpement en PHP
Pascal MARTIN
 
Le gameday...un concept devopsludique
Le gameday...un concept devopsludiqueLe gameday...un concept devopsludique
Le gameday...un concept devopsludique
EspritAgile
 
La Meta-programmation
La Meta-programmation La Meta-programmation
La Meta-programmation
Microsoft
 
Conference drupal 8 au Forum PHP 2013 à Paris
Conference drupal 8 au Forum PHP 2013 à ParisConference drupal 8 au Forum PHP 2013 à Paris
Conference drupal 8 au Forum PHP 2013 à Paris
Chipway
 
Solution Linux 2012 : Utilisateurs du Libre ne restez pas dans votre coin
Solution Linux 2012 : Utilisateurs du Libre ne restez pas dans votre coinSolution Linux 2012 : Utilisateurs du Libre ne restez pas dans votre coin
Solution Linux 2012 : Utilisateurs du Libre ne restez pas dans votre coin
Anne Nicolas
 
Mener à bien un projet Drupal (Drupagora 2013)
Mener à bien un projet Drupal (Drupagora 2013)Mener à bien un projet Drupal (Drupagora 2013)
Mener à bien un projet Drupal (Drupagora 2013)
LaNetscouade
 
Agile Day Tunisia 2012 - Quand le langage devient Agile
Agile Day Tunisia 2012 - Quand le langage devient AgileAgile Day Tunisia 2012 - Quand le langage devient Agile
Agile Day Tunisia 2012 - Quand le langage devient Agile
Tunisia Scrum User Group
 
Gestion de Projet et les outils Open Source
Gestion de Projet et les outils Open SourceGestion de Projet et les outils Open Source
Gestion de Projet et les outils Open Source
Martino Bettucci
 
edc à Documation 2016 - le futur de la doc
edc à Documation 2016 - le futur de la docedc à Documation 2016 - le futur de la doc
edc à Documation 2016 - le futur de la doc
Andy McDonald
 
Ms Experiences'16 gouvernance et choix des outils collaboratifs office 365
Ms Experiences'16   gouvernance et choix des outils collaboratifs office 365Ms Experiences'16   gouvernance et choix des outils collaboratifs office 365
Ms Experiences'16 gouvernance et choix des outils collaboratifs office 365
Patrick Guimonet
 
PHP : Une Plateforme Industrialisable Au Service De L'Agilité
PHP : Une Plateforme Industrialisable Au Service De L'AgilitéPHP : Une Plateforme Industrialisable Au Service De L'Agilité
PHP : Une Plateforme Industrialisable Au Service De L'Agilité
PHPPRO
 
Projet Confluence - Une base de données de type Wiki
Projet Confluence - Une base de données de type WikiProjet Confluence - Une base de données de type Wiki
Projet Confluence - Une base de données de type Wiki
MylneRoffi
 
Enib cours c.a.i. web - séance #6 : autour de la webapp
Enib   cours c.a.i. web - séance #6 : autour de la webappEnib   cours c.a.i. web - séance #6 : autour de la webapp
Enib cours c.a.i. web - séance #6 : autour de la webapp
Horacio Gonzalez
 
Challenges du recrutement pour un editeur de logiciel libre
Challenges du recrutement pour un editeur de logiciel libreChallenges du recrutement pour un editeur de logiciel libre
Challenges du recrutement pour un editeur de logiciel libre
Stefane Fermigier
 
Des jeux et des devops
Des jeux et des devopsDes jeux et des devops
Des jeux et des devops
Frederic Leger
 
Cours PHP 1/4 - Pierre Rudloff
Cours PHP 1/4 - Pierre RudloffCours PHP 1/4 - Pierre Rudloff
Cours PHP 1/4 - Pierre Rudloff
StrasWeb
 
[devops REX 2017] Les unconférences au cœur de l’évangelisation DevOps chez C...
[devops REX 2017] Les unconférences au cœur de l’évangelisation DevOps chez C...[devops REX 2017] Les unconférences au cœur de l’évangelisation DevOps chez C...
[devops REX 2017] Les unconférences au cœur de l’évangelisation DevOps chez C...
devops REX
 
PHP et Performances - AFUP 2005
PHP et Performances - AFUP 2005PHP et Performances - AFUP 2005
PHP et Performances - AFUP 2005
Eric D.
 
Partager des documents : les formats et les outils à utiliser ...
Partager des documents : les formats et les outils à utiliser ...Partager des documents : les formats et les outils à utiliser ...
Partager des documents : les formats et les outils à utiliser ...
Isabelle Motte
 

Similaire à Pourquoi la documentation compte ? (20)

Bonnes pratiques de developpement en PHP
Bonnes pratiques de developpement en PHPBonnes pratiques de developpement en PHP
Bonnes pratiques de developpement en PHP
 
Le gameday...un concept devopsludique
Le gameday...un concept devopsludiqueLe gameday...un concept devopsludique
Le gameday...un concept devopsludique
 
La Meta-programmation
La Meta-programmation La Meta-programmation
La Meta-programmation
 
Conference drupal 8 au Forum PHP 2013 à Paris
Conference drupal 8 au Forum PHP 2013 à ParisConference drupal 8 au Forum PHP 2013 à Paris
Conference drupal 8 au Forum PHP 2013 à Paris
 
Solution Linux 2012 : Utilisateurs du Libre ne restez pas dans votre coin
Solution Linux 2012 : Utilisateurs du Libre ne restez pas dans votre coinSolution Linux 2012 : Utilisateurs du Libre ne restez pas dans votre coin
Solution Linux 2012 : Utilisateurs du Libre ne restez pas dans votre coin
 
Mener à bien un projet Drupal (Drupagora 2013)
Mener à bien un projet Drupal (Drupagora 2013)Mener à bien un projet Drupal (Drupagora 2013)
Mener à bien un projet Drupal (Drupagora 2013)
 
Agile Day Tunisia 2012 - Quand le langage devient Agile
Agile Day Tunisia 2012 - Quand le langage devient AgileAgile Day Tunisia 2012 - Quand le langage devient Agile
Agile Day Tunisia 2012 - Quand le langage devient Agile
 
Gestion de Projet et les outils Open Source
Gestion de Projet et les outils Open SourceGestion de Projet et les outils Open Source
Gestion de Projet et les outils Open Source
 
edc à Documation 2016 - le futur de la doc
edc à Documation 2016 - le futur de la docedc à Documation 2016 - le futur de la doc
edc à Documation 2016 - le futur de la doc
 
Ms Experiences'16 gouvernance et choix des outils collaboratifs office 365
Ms Experiences'16   gouvernance et choix des outils collaboratifs office 365Ms Experiences'16   gouvernance et choix des outils collaboratifs office 365
Ms Experiences'16 gouvernance et choix des outils collaboratifs office 365
 
PHP : Une Plateforme Industrialisable Au Service De L'Agilité
PHP : Une Plateforme Industrialisable Au Service De L'AgilitéPHP : Une Plateforme Industrialisable Au Service De L'Agilité
PHP : Une Plateforme Industrialisable Au Service De L'Agilité
 
Projet Confluence - Une base de données de type Wiki
Projet Confluence - Une base de données de type WikiProjet Confluence - Une base de données de type Wiki
Projet Confluence - Une base de données de type Wiki
 
Enib cours c.a.i. web - séance #6 : autour de la webapp
Enib   cours c.a.i. web - séance #6 : autour de la webappEnib   cours c.a.i. web - séance #6 : autour de la webapp
Enib cours c.a.i. web - séance #6 : autour de la webapp
 
Challenges du recrutement pour un editeur de logiciel libre
Challenges du recrutement pour un editeur de logiciel libreChallenges du recrutement pour un editeur de logiciel libre
Challenges du recrutement pour un editeur de logiciel libre
 
Des jeux et des devops
Des jeux et des devopsDes jeux et des devops
Des jeux et des devops
 
Cours PHP 1
Cours PHP 1Cours PHP 1
Cours PHP 1
 
Cours PHP 1/4 - Pierre Rudloff
Cours PHP 1/4 - Pierre RudloffCours PHP 1/4 - Pierre Rudloff
Cours PHP 1/4 - Pierre Rudloff
 
[devops REX 2017] Les unconférences au cœur de l’évangelisation DevOps chez C...
[devops REX 2017] Les unconférences au cœur de l’évangelisation DevOps chez C...[devops REX 2017] Les unconférences au cœur de l’évangelisation DevOps chez C...
[devops REX 2017] Les unconférences au cœur de l’évangelisation DevOps chez C...
 
PHP et Performances - AFUP 2005
PHP et Performances - AFUP 2005PHP et Performances - AFUP 2005
PHP et Performances - AFUP 2005
 
Partager des documents : les formats et les outils à utiliser ...
Partager des documents : les formats et les outils à utiliser ...Partager des documents : les formats et les outils à utiliser ...
Partager des documents : les formats et les outils à utiliser ...
 

Pourquoi la documentation compte ?

  • 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
  • 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
  • 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

Notes de l'éditeur

  1. 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
  2. opensource Faire participer la communauté Quoi documenter ?
  3. Ventoux Sprints = montagnes et le dernier sprint pre release était le ventoux Comme je suis cycliste, cela me touche.
  4. Depuis la version 5.0 Basé sur Symfony 2 DemoBundle : contenu fictif pour comprendre l&amp;apos;implémentation des features =&amp;gt; sorte de documentation par l&amp;apos;exemple
  5. Qui aime faire de la doc ? Les docs existantes Personne ne veut le faire Mauvaise qualité de la doc DIY !
  6. Aider les gens à utiliser ce que mes collègues développent Permettre à des visiteurs de comprendre L&amp;apos;objet du logiciel et ses concepts Les features Comment faire Les bonnes pratiques Pour l&amp;apos;entreprise Publicité Méta-information : santé et vivacité
  7. 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
  8. Etre clair sur les versions Cohérence graphique Organisationnelle Nos choix - bugfix only sur doc legacy - @todo : améliorer la recherche
  9. Contenu de la page : - Blabla corpo - Peu de liens dans le menu - Couleurs sans relation avec le produit
  10. Habitudes de navigation Manuel utilisateur pour la version 5 Mais pas le manuel technique
  11. Gros travail sur la homepage =&amp;gt; Homepage plus claire - Accès à la doc legacy - Labels - Sujets mis en avant - Petite description du produit
  12. 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
  13. Doc effort week : Juste après avoir envoyé la release à la QA
  14. Inconvénients Pas d’information supplémentaire =&amp;gt; par rapport à qqn qui lirait le code La regen régulièrement sans quoi : obsolète =&amp;gt; tâche de maintenance supplémentaire à assurer (script ou regen manuelle) IDE peuvent se substituer à une doc contenant uniquement les arguments
  15. Avantage colonne  - passage obligé - visibilité de la charge Inconvenient - partie bloquante - dev peut déléguer la partie doc
  16. 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&amp;apos; entrée Lier des pages Communiquer entre la QA et les dev Veille documentaire Comment font les autres ? Pourquoi ?
  17. 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)
  18. 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é ?
  19. Coloration syntaxique Plusieurs langages Rendre clair les exemples Différencier les langages Outils existants et leur prix Nouvel outil = courbe d&amp;apos;apprentissage Workflow de dev Doc intégrée au workflow Chiffrer du temps pour la doc =&amp;gt; c&amp;apos;est comme les tests Maintenance de la doc =&amp;gt; ça prend du temps Equipe support Chacun a SA doc
  20. 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 =&amp;gt; Rejoint Lieu où placer la doc
  21. Collaboration : - écrire - demander, critiqueLa critique est aisée mais l&amp;apos;art est difficile. - corriger - proposer de supprimer
  22. Je n&amp;apos;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