Tutoriels, guides pratiques, référence technique et explications
Introduction
Cette catégorie est destinée à la documentation. Nous proposons d’utiliser une approche simple inspirée de la méthode « The Documentation System » qui considère la documentation selon deux axes : l’utilité et l’approche (pratique ou théorique).
Le système documentaire
LSD est une méthode pour écrire de la documentation technique. Elle consiste à créer des ressources utiles et complémentaires pour étudier un système (apprendre et comprendre) et le mettre en œuvre (résoudre des problèmes et consulter des références).
Partant du constat que la documentation des systèmes techniques est souvent confuse, elle propose de systématiser l’approche non pas en considérant une documentation unique, mais en considérant sa finalité. Ainsi, quatre angles apparaissent en fonction de l’objectif poursuivi et décline quatre manières d’approcher les documentations.
Source : The Documentation System
Cette méthode a été développée par l’agence Divio qui contribue largement au système de gestion de contenu Django, programmé en Python. L’un des principes de développement de ce logiciel libre et de ce langage de programmation est de « ne pas se répéter » (en anglais : Do not Repeat Yourself ou DRY – sec).
En voici une illustration :
Une série d’étiquettes est disponible exclusivement pour la #documentation.
| Tag | Finalité de la documentation |
|---|---|
| tutoriel | Mise en pratique d’étapes concrètes orientées vers l’apprentissage (plus utile lors de l’étude) |
| comment-faire | Mise en pratique d’étapes concrètes orientées vers la résolution d’un problème (plus utile dans l’action) |
| explication | Acquisition de savoirs théoriques orientés vers la compréhension (plus utile lors de l’étude) |
| référence | Acquisition de savoirs théoriques orientés par l’information (plus utile dans l’action) |
En outre l’étiquette faq [1], une forme de référence, permet de rassembler les réponses communes aux questions fréquemment posées dans le cadre de l’usage du forum ou du contexte des métiers du livre indépendant.
À faire
- Configurer la documentation dans Discourse
- Renseigner l’index (ce sujet)
- Établir un sujet pour nourrir la FAQ
- Documenter la création des diverses formes de documentation
- Créer au-moins une documentation de chaque type
FAQ, pour « foire aux questions », de l’anglais frequently asked/answered questions. ↩︎