📚 Documentation
Dans tout projet logiciel, deux types de documentation jouent un rôle essentiel, mais répondent à des besoins très différents: la documentation utilisateur et la documentation technique.
La documentation utilisateur s'adresse aux personnes qui utilisent le produit au quotidien. Son objectif est d'amener l'utilisateur à être autonome le plus rapidement possible. Elle ne présume habituellement pas de connaissances techniques.
La documentation de déploiement et technique s'adresse quant à elle aux personnes qui installent, configurent et maintiennent le système: administrateurs et développeurs. Contrairement à la documentation utilisateur, l'enjeu n'est pas de simplifier, mais d'être complet et précis, parce qu'une étape manquante peut compromettre toute la procédure.
Ces deux documentations partagent toutefois le même esprit. Elles sont écrites pour quelqu'un qui ne connait pas votre application ou votre système. Que ce soit un utilisateur qui découvre l'interface ou un administrateur qui déploie le système pour la première fois, une bonne documentation est celle qui permet au lecteur d'atteindre son objectif sans information supplémentaire.
Activité à faire en classe
Pour les articles de documentation suivants, nous allons relever ensemble les éléments distinctifs:
Documentation utilisateur
- https://help.miro.com/hc/en-us/articles/360017571974-Create-a-Miro-board
- https://docs.stripe.com/get-started/use-cases/startup
- https://www.airtable.com/guides/start/how-to-create-a-base
Documentation technique
- https://docs.gitlab.com/install/aws/
- https://docs.docker.com/get-started/docker-concepts/building-images/writing-a-dockerfile/
Guide pratique
Documentation utilisateur
Documentation technique / déploiement
Les outils de documentation
Plusieurs options s'offrent à vous pour rédiger et publier votre documentation. Chaque option vient avec son lot d'avantage et d'inconvénient.
Google Docs / Word
Avantages
- Aucune courbe d'apprentissage faible
- Collaboration en temps réel facile (particulièrement Google Docs)
- Partage simple avec un client externe via un lien ou un export PDF
- Mise en forme riche et flexible, insertion d'images et de tableaux facile
Inconvénients
- Difficile à maintenir à long terme
- Pas de visionnement structuré (« Guide_v3_final_VRAI_final.docx »)
- Le résultat ne ressemble pas à une documentation professionnelle, ça reste un simple document
- Aucune fonctionnalité de navigation intégrée (recherche, barre latérale, liens entre sections)
Docusaurus
Un générateur de sites de documentation open source créé par Meta. Le contenu est rédigé en Markdown et le site est généré automatiquement.
Avantages
- Produit un site de documentation professionnel, rapide et navigable
- Le contenu en Markdown est déposé dans un dépôt Git
- Recherche intégrée, barre de navigation, mode sombre — beaucoup de fonctionnalités de base sont incluses
- Gratuit et open source
Inconvénients
- Requiert un environnement technique pour le déploiement (serveur), malgré qu'il soit très facile de déployer avec Github Pages et Gitlab Pages.
- Partage privé limité. Docusaurus génère un site statique public par défaut. Pour restreindre l'accès à un client, il faut ajouter une couche d'authentification externe (proxy, VPN, plateforme avec contrôle d'accès), ce qui ajoute de la complexité. Il est possible de créer une page privée sur Gitlab, mais vous devrez donner accès à Gitlab à votre client.
Confluence et options alternatives (ex.: Notion)
Avantages
- Interface WYSIWYG facile pour créer le contenu
- Partage externe intégré. Possibilité d'inviter des utilisateurs externes
Inconvénients
- L'accès externe nécessite des licences invité ou un plan qui le permet
- La structure du site peut rapidement devenir chaotique
- L'expérience de lecture pour un client externe est correcte, mais loin d'un vrai site de documentation dédié