Dernière mise à jour : 10-03-2003
| Historique des versions | |
|---|---|
| Version 1 | 17/02/2003 |
| Premiers essais de mise en place | |
| Version 2 | 03/03/2003 |
| Information Cocoon/Docbook. Validation de la solution XXE/Docbook. Prise en compte des autres systèmes de doc. | |
Table des matières
Documentation technique interne : structuré, rapidement accessible, format pérenne, editable par tous, gestion des droits ?
Quelques liens utiles :
Le salon Documation : http://www.technoforum.fr/ avec notamment les livres blancs de Cosmosbay (décrit l'intérêt des données structurés, les besoins des industriels et les offres du marchés) et Improve.
DITA d'IBM (La solution de documentation "universelle" d'IBM.)
Table des matières
Format XML standard pour la documentation technique : incontournable. Difficulté pour l'éditer et le publier : c'est à dire peu d'outils Wysiwyg (voir plus loin XXE et Cocoon pour répondre à ce problème.)
Le Darwin Information Typing Architecture : Format XML pour la documentation technique. Beaucoup moins utilisé et supporté que Docbook. DITA réutilise beaucoup d'éléments de XHTML et de Docbook. Il est cependant très instructif de lire leur page d'accueil, la FAQ et plus. Cela permet de formaliser beaucoup de concepts. La structure de ce document est grandement inspiré de la lecture de ce site. C'est un peu le format idéal, mais il risque d'être trop long à apprendre et à mettre en oeuvre.
Format XML héritier du HTML. Simple à éditer et surtout à publier. Ce format permet de plus l'utilisation d'annotations et est particulièrement bien adapté à WebDAV.
Le Text Encoding Initiative est un standard qui aide les librairies, musées, éditeurs et universitaires à représenter tout type de texte pour la recherche en-ligne et l'éducation, en utilisant la structure la plus expressive et la moins sensible à l'obsolescence.
On voit rapidement que le but de TEI, encore plus que dans le cas de DITA, dépasse largement le périmètre du projet. Cependant il doit être instructif de parcourir leur site.
Table des matières
L'unité de documentation est le chapitre Docbook. Il permet de créer des documents entiers en réunissant des chapitres de diverses sources et d'avoir des sous-divisions : les sections Docbook. (Une section docbook ne peut contenir de chapitre.) Il est possible de réunir des chapitres dans des Part Docbook, mais il ne semble pas que l'élément Part soit bien supporté par les applications. Enfin il est possible de réunir plusieurs docbook en un grand Set docbook.
Voir Modular Docbook File pour l'utilisation de XInclude avec Docbook.
Il faudrait des modèles type de document, avec des chapitres que l'on retrouve à l'identique pour chaque domaine (Serveur, Réseaux, Site ...)
La documentation peut se diviser en plusieurs "sources" :
des fichiers XML avec une DTD spécifique pour définir la carte d'identité du client et ses services.
des fichiers XML Chapitre Docbook. qui peuvent être regroupés en book.
des Bases de données d'incidents, historiques d'interventions exportées aux formats XML ou nativement XML. (A créer.)
Table des matières
De tous ces outils, XXE ou Authentic sont à utiliser en priorité. D'une manière générale, il est préférable d'éditer directement le XML Docbook, plutôt que d'utiliser un traitement de texte (OpenOffice) qui rajoute une étape.
Permet d'éditer du XML. Il est très clair et préconfiguré pour le XHTML et Docbook. Il est par exemple possible d'imprimer directement le format Docbook. Il permet de créer un docbook complet ou des fragments de document (chapitre, section.)
Permet d'éditer du XHTML et dans une moindre mesure, du XML. Il est rapide, mais manque de robustesse et d'ergonomie (Il est possible de perdre des données en modifiant plusieurs fichiers simultanément.) Supporte les annotations.
Permet d'éditer du XML. Supporte WebDav. L'interface est très agréable.
Permet d'éditer du XML, notamment XHTML et Docbook. Le développement n'est pas assez avancé pour être vraiment intéressant. C'est une alternative à XXE : il est plus simple d'utilisation.
Il est possible de convertir les fichiers oo vers et depuis Docbook. De plus, il existe des modèles de documents avec des feuilles de styles "Docbook". Cette méthode est un peu lourde, il est préférable d'attendre qu'OpenOffice supporte le format Docbook en natif.
Le format de fichier de OpenOffice est du XML compressé. Il est possible d'enregistrer les documents en XML non compressé avec le filtre FlatWriterXML. Voir le travail E. Bellot : http://www.chez.com/ebellot/ooo2sdbk/.
Permet d'éditer du XML de manière très conviviale, mais un peu spéciale. Ils ont aussi une solution de CMS XML qui ressemble à Cocoon, mais en PHP et en allemand. A tester davantage.
Comment gérer la mise-à-jour des documents pour éviter d'écraser les modifications des autres. Deux solutions : dans le premier cas tous le monde peut éditer le document, dans le second, seul l'auteur est sensé prendre en compte les remarques des autres et modifier le document.
Chacun est responsable de ses documents. Si on veut une modification : il faut demander à l'auteur qu'il le fasse. Pour demander une modification, on peut utiliser :
les annotations. (Voir aussi : http://books.xmlschemata.org/relaxng/page3.html et http://annozilla.mozdev.org/)
Le mail
Chacun peut modifier les documents des autres. Dans ce cas il faut un outil de versionning :
CVS. A étudier.
Subversion (qui utilise WebDAV.) A étudier.
Naturellement, il faut prendre en compte l'avis des utilisateurs, sur la manière dont ils envisagent le problème. C'est à dire si il ne supportent pas que quelqu'un touche à "leur document".
Table des matières
Note : l'utilisation de ces outils est transparente pour l'utilisateur dans le cas de publication à l'aide de serveur de type Cocoon ou Forrest (voir plus bas.)
Ce sont les feuilles de style XSL qui permettent de générer différents formats (XHTML, PDF, PS, XSL-FO, ...) à partir du format XML Docbook.
Site : http://sourceforge.net/projects/docbook/. (Mode d'emploi, voir : Using the DocBook XSL Stylesheets.)
Il s'agit d'un parser Java. Il permet de faire des transformations XSL. (comme les docbook-xsl.)
Site : http://saxon.sourceforge.net/.
Il s'agit entre autre d'un parser en C. Il est plus rapide que SAXON. Son développement était moins avancé, mais il a rattrapé son retard. Développé pour Linux, il est portable sous différents environnements. Pour MS-Windows™ utiliser ce site et copier tous les .dll et .exe de libxml, libxsl et iconv dans un répertoire inclus dans le PATH (typiquement C:\WINNT\.) Il permet de faire des transformations XSL. (comme les docbook-xsl.)
FOP permet de générer des PDF, PS, SVG ... à partir du format FO. L'installation de FOP n'est pas triviale.
Télécharger FOP 0.20.5 de Apache http://xml.apache.org/fop/ .
Télécharger la bibliothèque JAI de SUN : http://java.sun.com/products/java-media/jai/(Choisir l'installation "CLASSPATH", mettre les fichiers dans le répertoire par défaut et copier les fichiers dans le répertoire lib de FOP.)
Telecharger éventuellement BSF d'IBM : http://oss.software.ibm.com/developerworks/projects/bsf (Je ne l'ai pas fait et cap marche.)
Table des matières
C'est ce qu'on utilise actuellement. Permet d'accéder à tout type de fichier, avec une préférence pour le format HTML et XHTML. Permet d'avoir un accès très rapide à l'information et donc d'être réactif face aux clients.
Rappelons qu'un traitement de texte est fait pour obtenir une impression papier et pas pour être consulté à l'écran ! Si on veut que la documentation soit réellement utilisée, il lui faut un support adapté.
Actuellement, il faut lancer des traitements pour obtenir les formats XHTML, PDF ... à partir des fichiers Docbook XML. Une infrastructure de publication XML permet de rendre ces traitements transparents. De plus, cela permet d'agréger des données de sources SGBD, LDAP ... Il sera donc possible d'intégrer des informations comme les incidents survenus, les modifications apportées sur un site web ou un serveur par la maintenance . Les 3 premiers sont des projets XML Apache.
C'est l'outil de référence pour les traitements XML. Il offre de nombreuses possibilité Authentification, LDAP, SGBD ...
Liens :
Utilisation de Cocoon avec Docbook : http://wiki.cocoondev.org/Wiki.jsp?page=DocbookTransformation
Il est basé sur Cocoon et spécialisé dans la mise en place rapide de documentation. A surveiller, puisque la version 0.5 en cours de réalisation supporte Docbook nativement.
Solution complète de CMS inspiré de Cocoon mais en PHP (=>Popoon) ... et en allemand. http://www.bitflux.ch/produkte/
La documentation est saisie directement au format Docbook sous forme de fragments de document par un outil convivial d'édition XML docbook de type XXE ou Authentic. Ces fragments de documents peuvent être agrégés entre eux et avec d'autres sources de données (ex. : base incidents, historique d'interventions) pour créer un document complet.
Il est possible d'agréger les fragments pour avoir par exemple un document relatif à un client et ses serveurs ou inversement à un serveur mutualisé et ses clients. Le but est de pouvoir réutiliser l'information et ne pas la saisir à plusieurs endroits. La documentation des statistiques des sites s'obtient en réunissant les chapitres "log" des documentations Apache et MS-IIS, ainsi que certains chapitres de l'application AWStats et du serveur qui l'héberge.
Une infrastructure de publication XML de type Cocoon ou Forrest permet de rendre transparente ces opérations et de publier les docbook qui sont consultable aux formats XHTML, PDF ou autre. On peut utiliser l'authentification pour gérer des droits en lecture.