Écrire de la documentation de manière incrémentale et en allant d’une information contextualisée pertinente à une information plus spécialisée résume l’approche documentaire que nous préconisons:

  • Commencer avec de la documentation basique in-situ et l’intégrer dans l’interface du produit documenté
  • Si possible, contextualiser cette information
  • Ecrire ensuite les autres types de documentation en fonction du besoin

Pourquoi bâtir du bas vers le haut

Eh bien, c’est la plus vieille approche architecturale au monde. Elle garantit que vous avez traité l’information essentielle au bon endroit, où l’utilisateur en a besoin, facilement accessible, et devant lui.

Qu’est-ce que de la documentation contextuelle in-situ ?

Notre approche sous forme de blocs d’informations est très utile lorsqu’il s’agit de livrer de la documentation in-situ directement dans l’interface du logiciel cible. Il est alors possible de concevoir une matrice d’information en se posant les bonnes questions:

  • Qu’est ce que ceci ? Quelle est son utilité ?
  • Comment je l’utilise ?
  • Existe t il des exemples ?
  • Ou me situe-je dans le flux métier ?
  • Que dois-je faire ensuite ?
  • Quels pièges dois-je éviter ?

Ceci représente une matrice éditoriale, un guide de contenu. En aucun cas il ne faut remplir tous les blocs d’information comme s’il s’agissait d’un formulaire. C’est une aide pour que le rédacteur puisse se poser les bonnes questions.

D’autres formes d’informations selon le besoin ?

Les autres formes d’information sont considérées comme additionnelles, avec par exemple:

  • des FAQs
  • des étapes de procédures
  • des concepts
  • de la théorie
  • ce que DITA appelle « Reference » information

Les logiciels que nous rencontrons fournissent des procédures inhérentes à un domaine technique bien spécifique. Les utilisateurs ont un minimum de connaissances à propos du domaine concerné. Il n’est donc pas nécessaire de leur apprendre leur métier, mais plutôt comment le logiciel va les aider à le faire.

Aujourd’hui, les approches Agile en matière de développement logiciel tendent à façonner et à régler les applications selon ce que souhaitent précisément les utilisateurs. Théoriquement, cela devrait alléger la charge documentaire.

Alors que reste-t-il à expliquer ?

  • les approches particulières adoptées par le logiciel
  • les concepts développés pour aider l’utilisateur à se repérer
  • les pièges à éviter
  • la terminologie si elle est inhabituelle
  • des résultats illustrés par des exemples
  • un corpus de questions fréquentes pouvant être réutilisé en tant que support du logiciel