Bienvenue !

Microsoft Office Word, inadapté

Word est un logiciel de traitement de texte. Il n’est pas destiné à générer de la documentation technique, d’autant plus si celle-ci doit être modulaire. Ce n’est pas un format structuré (la structure du document ne respecte pas de schéma défini), il ne dissocie pas le fond de la forme et le principal format d’export est le PDF.

Les LML, pour la documentation logicielle

Dans le cas d’une documentation logicielle, la tendance actuelle est aux formats non structurés dits à balisage légers (Lightweight Markup Language) tels que Markdown, reStructuredText ou asciidoc. Markdown a l’avantage d’être très répandu mais l’inconvénient de présenter une multitude de variantes non compatibles entre elles et un format moins sémantique que les deux autres. Ces documentations sont ensuite publiées sous forme de site web statique (HTML) flexibles et conviviaux par des générateurs de documentation (Sphinx, Asciidoctor).

DocBook, la simplicité

DocBook est un format de documentation structurée. Initialement, DocBook permettait d’élaborer des documents monolithiques. Depuis sa version 5.1, DocBook suit l’évolution actuelle et permet aussi de développer des contenus modulaires, même si cette modularité est moins poussée que pour DITA.

DITA, universelle

Dans le domaine de l’industrie, la spécification DITA est en train de se généraliser. Plus qu’une simple architecture de document XML, DITA permet de concevoir, rédiger, gérer et publier du contenu modulaire. DITA est flexible dans l’organisation de l’information et permet :

• la réutilisation de contenu (réduction des coûts de rédaction et de traduction),
• le single-sourcing avec de multiples formats de publication possibles (PDF, HTML5, XHTML, Epub, Kindle, etc.),
• l’automatisation des processus de création documentaire.

Contrairement à d’autres spécifications plus rigides, DITA s’adapte à tout type de structure d’information grâce à son mécanisme de spécialisation.

S1000D, pour les projets complexes

La spécification S1000D, quant à elle, est plus complexe avec des règles plus strictes. En contrepartie, cela rend cette spécification adaptée à des programmes complexes et très structurés tels qu’on peut en trouver dans le domaine aéronautique, ainsi que dans le domaine naval et ferroviaire. Tout comme DITA, la S1000D offre des gains de productivité et de qualité de l’information grâce à sa structure modulaire.

Conclusion

Outre les caractéristiques de chaque format de rédaction, le choix dépend de plusieurs autres paramètres comme les outils d’édition et de publication associés ou le type de profil qui doit contribuer à la mise à jour de la documentation.