La documentation logicielle se transforme en gestion de stratégie de contenu collaborative et agile, pourquoi et comment?
•Télécharger en tant que PPTX, PDF•
1 j'aime•437 vues
Notre conférence à DOCUMATION 2106 pour le francophones. Une prise de vue des nos techniques, normes et métier confrontés à la vision d'éditeurs de logiciels dévoile un déphasage important. Nous devons agile.
Recommandé
Contenu connexe
En vedette
Similaire à La documentation logicielle se transforme en gestion de stratégie de contenu collaborative et agile, pourquoi et comment?
Similaire à La documentation logicielle se transforme en gestion de stratégie de contenu collaborative et agile, pourquoi et comment? (20)
La documentation logicielle se transforme en gestion de stratégie de contenu collaborative et agile, pourquoi et comment?
- 1. State of the art Technology Traitement de texte SGML Internet XML DITA Norms Madia Training
- 2. Use cases Julie Vivien, rédactrice technique Tech’advantage Responsable documentation utilisateur pour le compte de Total
- 3. Expérience Périmètre Domaine géosciences multidisciplinaire De multiples intervenants • 2 rédacteurs techniques - 80% du contenu • 4 intervenants du client • > 20 intervenants ponctuels spécialistes métier • 2 autres équipes internes ou en sous-traitance
- 4. Expérience Périmètre Planification agile Outil développé par Tech’advantage • doc contextuelle connectée au produit • doc connexes, FAQ, procédures, référentiel • livraison hebdomadaire Méthodes
- 5. Expérience Périmètre 2012 – 2014 • priorité : quantité d’interfaces documentées 2014 - 2015 • bases du logiciel couvertes • retours d’utilisateurs • la priorité évolue • qualité plutôt que quantité • docs connexes pointus • méthodologie pour réduire le besoin en doc Méthodes Chantier 2015 – 2016 • priorité : les nouveautés • par conséquent, accès plus facile aux experts
- 6. Expérience Périmètre Pistes d’évolution exprimées • moteur de recherche • 950 interfaces documentées • et 1680 documents connexes • navigation thématique ou taxonomique • notre approche est centrée IU • les lecteurs doivent se situer dans leurs process métier Méthodes Chantier Evolution • participation du client • annotation, commentaires et contributions en consultant la doc dans leur produit • stats analytiques pour gouverner la maintenance • ergonomie et terminologie IU • nouvelles formes ludiques, animation, vidéo, une approche e-learning
- 7. Expérience Christophe Aug, Beicip/Franlab, filiale IFPEN Responsable ligne de produits et plateforme Nicolas Philippe, rédacteur technique TECH’advantage Accompagnement de la transformation
- 8. Expérience Périmètre Domaine géosciences multidisciplinaire Une plate-forme logicielle • 7 produits • une doc pour chacun • chacun a son style, sa forme • avec zones de recouvrement Avec TECH’advantage – refonte de l’ensemble
- 9. Expérience Périmètre Introduction de la doc contextuelle Effort important de transformation de l’existant • sortir le contextuel • créer les autres structures Réorganisation éditoriale Méthodes
- 10. Expérience Périmètre La doc embarquée avec le produit est appréciée Effort minimalisé de mise à jour Réduction considérable de volume Méthodes Résultats
- 11. Expérience La refonte n’est pas spontanée Rendre une équipe pluridisciplinaire cohérente • Guide de styles • Assistance dans l’édition • Relecture et retours Aujourd’hui, ce sont les bases d’une stratégie éditoriale www.doccontents.com Evolution Périmètre Méthodes Résultats
- 12. Ce dont nous disposons : • des technologies • des normes • un métier • du savoir-faire • de l’expérience Constat
- 13. Etude Thibaut Baron Cabinet Gtec Dirigeant & Consultant Senior
- 14. Etude Périmètre Concernant l’implémentation de la documentation utilisateur Auprès d’éditeurs de logiciels • startups / ETI • centrés marché français / international • business model traditionnel / SaaS • solutions installées / Web • logiciels propriétaires / open source
- 15. Etude Périmètre La Doc : un boulet pour les éditeurs de logiciels • ils restent figés dans un modèle de conception et sont confrontés à de fortes problématiques d’obsolescence Une Doc figée dans une forme et un process des années 1990 • création et process de mises à jour fortement décorrélés du développement logiciel même en mode agile • en général, ils réalisent la doc “à côté” de leur solution logicielle, peu interactive et systématiquement obsolète Conclusions
- 16. Etude Périmètre Une incapacité à réinventer le modèle • ils se contentent du service minimum • certains vont même jusqu’à assumer l’absence de doc pour leurs solutions • même lorsque l’innovation logicielle est au cœur de leurs préoccupations • ils peinent à réinventer un nouveau modèle de doc performant, intégré et réellement consulté par leurs utilisateurs La doc est vécue comme un centre de coûts, et non comme un levier de valeur ajoutée Conclusions
- 17. Editeurs de logiciels Quelle motivation ? • une vraie valeur ajoutée • la satisfaction de leurs utilisateurs • image de marque
- 18. Editeurs de logiciels Que pouvons-nous leur proposer ? • prendre la main • mieux comprendre ce que nous apportons • insérer la production de la doc dans leurs process
- 19. Editeurs de logiciels Que pouvons nous leur proposer ? • devenir décisionnaire - en définissant une stratégie de contenu • bâtir le contenu de manière agile - du bas vers le haut • travail collaboratif
- 20. Stratégie de contenu Fixe les objectifs Définit l’audience Détermine les canaux Décide du contenu Organise les sources Organise la validation
- 21. Construction incrémentale Du bas vers le haut • documenter l’IU • ajouter les sujets connexes • commenter, contribuer • valider • publier
- 22. Construction collaborative Qui collabore et comment ? • développeurs et rédacteurs • le support • les experts
- 23. Rédacteurs - évolution de leur rôle Au-delà de la rédaction • architecte - structure de contenu • garant - cohérence éditoriale • animateur - cycle production
- 24. Stand B29
Notes de l'éditeur
- Marie-Louise Flacke: Bonjour, Merci d'être là et de vous joindre à nous pour parler de notre sujet favori : la creation de documentation ! En a-t-on vraiment besoin ? Puisque les logiciels sont de plus en plus "intuitifs", pourquoi ajouter du texte a ce que l'on a déjà compris? Et pourtant, certains persistent à produire de la documentation. On se demande comment ils font. Ils démarrent non plus avec une page blanche, mais probablement un écran blanc...
- Marie- Louise Flacke: Je vais parler très rapidement de l’état de l’art mais nous allons aussi parler de collaboration avec les développeurs et aussi avec les utilisateurs, du point de vue de ceux-ci et des éditeurs de logiciels eux-mêmes. Nous avons dans l'arène aujourd'hui à ma droite Thibaut Baron du cabinet Gtec, qui nous parlera d’une étude auprès d’éditeurs de logiciels en France. Julie Vivien, rédactrice technique, intervenant à Total, qui nous parlera des résultats de deux ans de refonte complète de leur documentation. Christophe Aug, responsable d’une gamme de produits à Beicip/Franlab filiale IFPen qui parlera de la reprise de l’ensemble de leurs documentation. Nicolas Philippe, rédacteur technique de son état qui va parler de la transmission de son savoir à des collaborateurs n’étant pas formés à la rédaction technique mais devant tout de même en écrire, et à ma gauche, Andy McDonald qui vous parlera de la solution EDC pour la conception de documentation
- Before we get into the heart of the subject, let’s just agree on the state of our art today. A lot of us have seen technology, norms and media evolution especially since the internet explosion. Today there is a lot of hype around social networking, and we’re all involved in that. We have all training ine one way or another, and experince that has led us to where we are. We spend a lot of time concentrated on things like DITA, pondering about what is the best way to get a message across, and for such we all have our own preferences. We’re convinced we know how to do a good job.
- Julie Vivien Bonjour et merci Marie-Louise,
- Julie Vivien Je suis responsable du projet de documentation d’un grande plate-forme de logiciels géosciences, un domaine que je ne maîtrise pas d’emblée. Une équipe pluridisciplinaire intervient : 2 rédacteurs techniques à temps plein qui produisent environ 4/5èmes de la doc 4 intervenants Total participent de manière régulière à la doc + une vingtaine d’autres qui participent ponctuellement sur les sujets pointus en qualité d’experts 2 autres équipes, interne ou en sous-traitance (env. 6-7 personnes) séparées font également de la documentation en utilisant nos outils et méthodes. Les 2 rédacteurs techniques sont garants de la cohérence globale de la doc au niveau du produit.
- Julie Vivien La particularité du projet est sa planification et organisation en mode agile Pour la documentation, nous utilisons notre propre outil installé chez le client: - le point d’entrée de la doc est un mode contextuel que les développeurs implémentent. - ensuite nous produisons toute la documentation connexe, faq coordonnée avec le support et documentation référentiel écrit avec des spécialistes quand c’est possible – ils ne le sont pas, donc on passe beaucoup de temps à les pister. - la doc est livrée toutes les semaines
- Julie Vivien Historique du chantier documentation depuis 2012 quand nous l’avons pris en charge: (ne pas citer le nom du produit) En 2012, quand nous sommes arrivées sur le chantier, il y avait très peu de documentation et ce qui existait était inégal dans la qualité et la forme La priorité est faite à la documentation contextuelle, donc la quantité, mais de manière assez superficielle. En parallèle, nous avons mis au point notre propre outil inspiré de DITA et formé tout le monde à son utilisation. Fin 2014 / 2015 : les bases du logiciel sont couvertes, les utilisateurs qui auparavant ignoraient la documentation recommencent à s’en servir, ils expriment leurs besoins : la priorité évolue. Focus sur la qualité plutôt que la quantité. Contexte particulier : les utilisateurs sont des experts de leur partie, qui ont besoin d’une information avancée et hautement pertinente sur les principes scientifiques et les méthodes de calcul utilisées par l’application plutôt que d’instructions pour utiliser l’interface. On documente moins d’interfaces, et on créée plus de documentations connexes très pointues et très pertinentes avec l’aide d’experts métier. Pour réduire le plus possible le besoin de documenter les interfaces, participation des rédacteurs techniques à certains développements en tant qu’experts en ergonomie, afin d’aider à avoir une terminologie cohérente et une interface intuitive. Fin 2015 / 2016 Nous en sommes à la troisième version documentée du produit. => la priorité continue à évoluer. Le focus est toujours sur une documentation pointue, mais elle doit maintenant concerner en priorité les développements les plus récents (nouveautés présentes dans la dernière version produit). Accès plus facile aux experts métier, puisque le travail de développement est récent, les gens sont toujours présents et leur mémoire est fraîche. Bonus pour la qualité de la doc.
- Julie Vivien Direction à prendre à l’avenir : Des besoins exprimés restent à traiter : Moteur de recherche pour la doc : le volume de doc est énorme. 946 interfaces documentées (équivalent d’entre 800 et 1000 pages word) et 1680 documents connexes (environ 1000 à 1200 pages word). Il faut pouvoir faire le tri. La doc de base autour de laquelle est construite le reste est la doc contextuelle, donc on a une approche centrée sur l’interface. Mais l’utilisateur a un besoin process, donc il a du mal à trouver l’info. Besoin de mettre en place un moteur de recherche taxonomique calé sur les process métier. Forte demande d’une plus grande participation du client à la doc. Possibilité de faire des retours directs lors de la lecture. Amélioration continue de l’ergonomie et la terminologie des interfaces Il faut aussi anticiper les futures évolutions des besoins : Mise en place de stats de lecture : en sachant quels docs sont utilisées (ou non) on peut voir sur quelles parties de l’application faire des efforts, et aussi voir si les docs populaires ont des caractéristiques spécifiques (plus ou moins d’images, longueur, etc.) applicables à la doc au sens large Opportunité de rendre la doc plus ludique et plus interactive. Doc surtout texte à l’heure actuelle. Nous allons étudier l’opportunité d’utiliser des formats plus visuels (bd, captures d’écran annotées, animations, vidéo, etc.) et de mettre en place une vraie stratégie d’e-learning qui à l’heure actuelle n’existe pas.
- Christophe Aug Bonjour et merci Marie-Louise,
- Christophe Aug Beicip/Franlab intervient également dans le domaine géosciences, cette fois-ci orienté bassin, réservoir, simulation et gestion des incertitudes. Nous avons une plate-forme technologie et 7 produits, chacun avec sa spécificité. Historiquement toute notre documentation, en Anglais uniquement, était faite avec Word. On s’est retrouvé avec des formes, des styles et un contenu très disparate. Avec Tech’advantage et Nicolas Philippe nous avons complètement remodelé notre documentation.
- Christophe Aug Nous avons accepté très vite la notion de documentation contextuelle, car elle permettait de séparer l’information dont l’utilisateur avait besoin au prime abord, de toute l’information process et métier. La transformation initiale a pris du temps parce qu’il fallait adapter nos produits pour gérer cette doc contextuelle. Par la suite, cela permettait une maintenance plus aisée. Ensuite avec Nicolas, nous avons tout ré-architecturé ensemble. Je me suis occupé de la cohérence produit, et lui de la cohérence éditoriale. Aujourd’hui nous en sommes à la quatrième version de cette documentation. Tout le processus nous a permis d’élaguer l’existant, de rester cohérent en produits et d’éviter de la redite. La navigation s’est trouvé grandement améliorée et le résultat a été reconnu comme une valeur ajoutée à notre gamme de produits commerciale.
- Nicolas Philippe Bonjour et merci Marie-Louise,
- Nicolas Philippe Le rôle que j’ai pu joué avec Beicip/Franlab laisse entrevoir un des nouveaux rôles de rédacteur technique. J’ai passé beaucoup moins de temps à rédiger, qu’a encadrer avec différents axes : Définir une Stratégie éditoriale Guide de transfert, guide de style Animer une communauté de non rédacteurs Assistance éditoriale à distance Relecture et contrôle qualité
- Marie-Louise Flacke C’est très bien tout ça – nous avons de la technologie, des normes, un métier et de l’expérience… A priori nous avons tout ce qu’il faut pour produire une documentation moderne et multi-canal Allons voir ce que pensent les éditeurs de logiciels. En fait… il sont après tout nos clients…
- Thibaut Baron Bonjour et merci Marie-Louise,
- Thibaut Baron Gtec a mené pour le compte de Tech’Advantage une étude sur la Documentation Utilisateurs, sur un échantillon d’éditeurs de logiciels français de tous types (startups / ETI - centrés sur le marché français / internationaux - business model traditionnel / SaaS - solutions OnPremise / Web - logiciels propriétaires / open source).
- Thibaut Baron La Doc : un boulet pour les éditeurs de logiciels Les conclusions de l’étude sont sévères : alors que la plupart des éditeurs reconnaissent que la Doc demeure une exigence forte de leurs prospects et clients, ils restent figés dans un modèle de conception traditionnel et sont confrontés à de fortes problématiques d’obsolescence du support. Une Doc figée dans une forme et un process des années 1990 L’étude révèle notamment une création et des process de mises à jours de la Doc (quand ils existent) fortement décorrélés du développement logiciel. Cela est particulièrement frappant chez les éditeurs qui ont adopté les méthodes agiles de type Scrum : avec l’accélération du Time to Market et la mise en production de nouvelles versions tous les 15 jours, les éditeurs excluent la documentation Utilisateurs de leurs process : ils réalisent donc en général une Doc “à côté” de leur solution logicielle, peu interactive et systématiquement obsolète. Et cela est encore plus marqué chez les éditeurs internationaux, en raison de la complexité supplémentaire qu’implique le multilinguisme
- Thibaut Baron Une incapacité à ré-inventer le modèle La plupart des éditeurs de logiciels français prennent acte de cet état de fait et se contentent donc du service minimum ; certains vont même jusqu’à assumer l’absence de Doc pour leurs solutions. Il est particulièrement frappant de constater qu’alors que l’innovation logicielle est au coeur de leurs préoccupations, ils peinent à ré-inventer un nouveau modèle de Documentation Utilisateurs qui soit performant, intégré à leurs processus et réellement consulté par leurs utilisateurs. La Doc est vécue comme un centre de coûts, et non comme un levier permettant d’ajouter de la valeur à leur offre logicielle.
- Andy McDonald Merci Thibaut pour cette analyse du point de vue de nos clients. En effet, ceux qui vont nous commander de la documentation sont aussi à convaincre de l’utilité de ce que nous faisons. On va essayer de regarder la situation de leur point de vue alors et examiner ce qui peut les motiver, ensuite on verra comment s’y prendre et ce que cela change pour nous. La motivation d’un éditeur de logiciel tourne autour de retours plus au moins tangibles, tout en dépensant le moins possible. Ces retours sont soit, une vraie valeur ajoutée de promotion à son produit, une promesse de meilleure satisfaction utilisateur et une vision de comment on va l’atteindre. (retravailler) Le retour en image de marque est moins convaincant surtout quand on voit que cet argument ne les a pas motivé pour faire de la doc auparavant.
- Andy McDonald La méthodologie que nous mettons en avant les implique dans l’ensemble du processus de fabrication et les aide à faire des choix. Ils restent décissionnaires et ils contrôle mieux l’ensemble. Ils ont une meilleure vision tout au long sur ce que nous faisons. Nous collons à leurs processus de fabrication logicielle. Typiquement ils développent en cycle en V ou en mode agile. Nous allons devoir leur proposer une solution qui s’adapte aux deux. On parle beaucoup d’agilité et documentation. C’est un peu à la mode. On va voir comment on proposera, nous, d’y aller…
- Andy McDonald Nous apportons quelques nouveautés à la fabrication de documentation utilisateur. Le premier, c’est la gestion d’une stratégie de contenu et le deuxième concerne une construction plus agile qu’avant, en abordant la documentation du bas vers le haut – partir de l’IU et imaginer quel contenu connexe est ensuite nécessaire.
- Andy McDonald La notion de stratégie de contenu n’est pas nouveau ou complexe en soi. Cette stratégie est définie par l’éditeur, son responsable produit, ou en mode agile, son product owner. A défaut, c’est a nous, spécialistes de l’information de savoir l’accompagner dans cette démarche. Fixer les objectifs Se définir une vue d’ensemble du projet de doc, son étendue, les contraintes et éléments de référence du projet existants. Par exemple, pour la V2 de mon produit, je ne m’occupe que de ce qui est nouveau en me concentrant sur la prise en main et les faq pour le support. Définir l’audience Mes utilisateurs sont des experts dans leur métier. J’ai besoin de leur apprendre comment adapter des méthodes pour utiliser mes nouveautés et de mesurer vite leur adhésion. Les canaux Il s’agit de décider en amont les canaux de diffusion. Par exemple: 1. la doc in situ, 2. Le support, et 3 Mon portail de doc. Structure de contenu Très fortement lié au choix de canaux. Par exemple – Doc contextuelle avec surtout des informations d’utilisation, Un glossaire de terminologie nouvelles, des fiches métier indiquant ce qui change, et des faq à imaginer avec le support. Organisation des sources Les sources sont à la fois les cahier de charges, et surtout les hommes, experts, product owners. L’intérêt est de le définir à l’avant et les sensibiliser sur leur rôle et contribution. Organiser la validation Déterminer qui valide.
- Andy McDonald Dans la production de contenu, nous cherchons volontairement un cycle court. Le parti pris que nous avons adopté, est de créer en premier lieu une doc in-situ, traitant uniquement du contexte d’utilisation locale. C’est un point d’entrée pour le reste du contenu connecté par des liens, là où c’est nécessaire. Nous livrons l’ensemble très tôt au produit, pour qu’il soit testé. Les testeurs peuvent être les responsables produit, le support et même des utilisateurs choisis. Un de nos enjeux sera de faire collaborer un ensemble de contributeurs, y compris les utilisateurs. La publication peut être multi-canal. Qu’est-ce qu’ on entend par là : - dans le produit sur un portail. sous forme de support sous forme de tutoriel.
- Andy McDonald Une documentation ne se construit pas tout seul. Nous avons intérêt à faire participer tout les acteurs-clés autour du produit et surtout des experts métier. Le développeurs instancient les briques de l’IU à documenter. Le rédacteur les documente. En plus, ce couplage permet au rédacteur d’avoir un avis sur l’ergonomie et la terminologie. Dans ce mode de fonctionnement agile il intervient assez tôt et souvent il est un des premiers utilisateurs. Le responsable produit ou le product owner en mode agile est à même de fournir les concepts et la structure de workflow. Le rédacteur n’a pas du coup tout à écrire, mais il harmonise et rend cohérent. Les experts contribuent du contenu métier.
- Andy McDonald Intro: indiquer focus sur le métier de la rédaction. Le rôle du rédacteur dans ce type de modèle de construction évolue : Il devient architecte d’une structure d’information et garant de sa cohérence Il devient garant de la ligne éditoriale. Il aide les autres intervenants à comprendre ce que l’on attend d’eux. Il anime un cycle de production de contenu en sollicitant les interventions des acteurs identifiés. Il livre régulièrement