• Exemple: logiciel Stog
• Une forêt inconnue
• Des sites remarquables
• Des chemins

• Un compilateur de documents XML ⇒ XML (et donc XHTML)
• ... pour faire des sites web, blogs, documentations, mais aussi des articles,
• Pas de nouvelle syntaxe: tout en XML mais support de Markdown et ,
• Basé sur un système de réécriture et des patrons,
• Plusieurs règles par défaut mais possibilité de (re)définir les siennes,
• Gestion des liens internes, tables des matières, fils RSS, mots-clés, ...,
• Vient avec un serveur de prévisualisation,
• ... et un serveur d'édition en ligne utilisant git,
• Des greffons permettent l'ajout de fonctionnalités (production de graphes RDF, intégration de figures au format dot, asymptote, ...).

Exemples d'utilisation:

• Support de formation OCaml,
• Site web de logiciels (incluant la documentation): Stog, OCaml-RDF,
• Site web du SED,
• Article de maths.

Utilisateurs:

• Rédacteurs: des personnes qui écrivent en XML ou Markdown,
• Développeurs: des personnes qui ajoutent des greffons en OCaml, ou qui proposent des corrections ou des améliorations.

⇒ documentation pour ces deux types d'utilisateurs.

Considérons un logiciel comme une forêt inconnue.

La documentation doit permettre d'apprendre cette forêt, y prendre ses repères, comprendre son organisation.

Pour cela, à partir d'une entrée unique, le site web, on propose des chemins à emprunter, sortes de parcours pédagogiques et thématiques.

Par pitié, ne produisons plus de documentation en PDF: la documentation en ligne est bien plus pratique.

Les différentes documentations de Stog sont toutes dans le même site web: présentation, téléchargement, installation, didacticiels, documentation utilisateur par thème, documentation de référence des modules.

Tout le site est généré avec Stog lui-même (bootstrap!).

La documentation de référence est extraite des commentaires du code avec ocamldoc augmenté par un générateur fourni dans Stog, pour que les fichiers XML générés par ocamldoc puissent être utilisés comme sources par Stog.

⇒ Les liens vers la documentation de référence sont vérifiés à la compilation du site.

⇒ Les exemples de la documentation sont exécutés à la compilation et donc à jour.

La documentation contient des «sites remarquables», des points centraux, comme

• les départs de parcours pédagogiques (tutoriels, documentation de référence, ...) mais aussi
• les descriptions de concepts, structures, modèles et algorithmes utilisés dans le logiciel.

Pour Stog, on trouve une page «Documentation» avec des liens vers

• des didacticiels (première utilisation, utilisation sur des documents simples, création de greffons),
• la présentation du fonctionnement par aspect: lancement, règles de réécriture, règles prédéfinies, document principal,
• la documentation de référence des modules OCaml,
• la présentation du serveur de prévisualisation.

On peut accéder au code source de chaque page du site, en guise d'exemple.

Une figure illustrant le fonctionnement des différentes phases de traitement contient des liens menant aux structures de données correspondantes dans la documentation de référence.

Les liens entre les éléments (pages) du site web sont comme des chemins dans la forêt du logiciel: ils permettent de s'orienter et d'atteindre facilement un endroit proche de ce que l'on cherche.

Pour le développeur, ces chemins servent de points de départ pour aller voir le code (une fonction, un module) d'où il peut parcourir des «sentiers» (appels de fonctions, ...) pour acquérir une meilleure vision du fonctionnement.

Dans Stog, la figure illustrant le fonctionnement permet de savoir à quel endroit dans le code on peut commencer à regarder pour, par exemple, la représentation interne des informations, les modules de transformation des documents, ...

• Pas (encore) de pages man,
• Certaines fonctionalités pas encore documentées,
• Relecture et mise à jour à chaque libération: entretien des chemins et des sites; ça prend du temps,
• Le site de Stog fait avec Stog permet d'avoir un test grandeur nature,
• Avec un temps limité, il faut attendre la "bonne saison" pour défricher et entretenir: pas la peine de documenter quand ça pousse un peu partout; mieux vaut attendre une stabilisation des fonctionnalités,
• Mieux vaut aussi documenter quand on a envie de transmettre et d'expliquer,
• Attirer de nouveaux visiteurs et avertir les visiteurs réguliers: un blog signale les libérations et les nouvelles fonctionnalités.

Mise en ligne:

• make webdoc compile tout le site,
• utilisation de github-pages: commit + push pour mettre en ligne.