Your SlideShare is downloading. ×
  • Like
Pourquoi la documentation compte ?
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×

Now you can save presentations on your phone or tablet

Available for both IPhone and Android

Text the download link to your phone

Standard text messaging rates apply

Pourquoi la documentation compte ?

  • 988 views
Published

 

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
988
On SlideShare
0
From Embeds
0
Number of Embeds
10

Actions

Shares
Downloads
2
Comments
0
Likes
1

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    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

Transcript

  • 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
  • 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. 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. 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. 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. 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. 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. 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. 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. Merci ! Questions ? sarah.haim@ez.no Twitter @mereteresa Where Content Means Business