Revoir la documentation

De zéro à héros, rédiger pour les Castors Juniors

@m4d_z
alwaysdata
m4dz's avatar
m4dz

Paranoïd Web Dino · Tech Evangelist

alwaysdata logo
https://www.alwaysdata.com
Il était une fois… la documentation

La véritable histoire de toute documentation
c’est que personne ne sait comment bien faire
(et que c’est toujours le bordel au bout d’un moment)

Les Castors Juniors : le parfait manuel
  • Chaîne documentaire
  • Structuration de données
  • Participation & Partage

💡

  • Le code
  • Les projets
  • Les plateformes
  • Les outils

→ Les communs

Au commencement était le manuel

Personne n’est obligé
d’utiliser votre produit

Y a pas de doc

Doc minimale :

  • Pré-requis
  • Démarrage rapide
  • Licence
  • Contributions
  • Support

Le basique : un README

Maintenance 🔫

  • Abondance d’info
  • Approche structurelle
  • Risque important de décorrélation

Level Up : le wiki

Structure 🔫

  • Séparation des contenus
  • Cohésion / validation

Niveau Master Mind: le projet

🔫

  • Curation des contenus
  • Obsolescence
  • Contribution

On s’attache trop à l’outil

Les bonnes questions™

  • Qui accède au contenu ?
  • Comment rechercher l’information ?
  • Pourquoi contribuer ?

Le plus : la communauté

Le Guide du voyageur

Read The Fucking Manual

Tout sauf 🔫

  • Inclusif
  • Bienveillant
  • Précis

Quand ai-je besoin
de la documentation ?

Je suis développeur (à la base)

J’ai tendance à découper les ensembles en sous-éléments simples pour comprendre leurs relations naturelles

Je suis biochimiste

Les choses sont plus claires et plus simples à retrouver quand elles sont rangées et classifiées selon des jeux de règles strictes

The Taxonomy Database · NCBI
The Taxonomy Database · NCBI

Je suis un créatif

Plus les choses sont visuelles, illustrées, plus elles sont simples à comprendre et à appliquer

L’accès à la doc

  1. Recherche
    élément précis
  2. Corpus
    thématique dédiée
  3. Lecture
    linéaire progressive
Interlude pâtisserie

La réponse ultime :
le livre de recettes !

📖

  • Recettes : contenus textes et illustrations
    → pages de doc
  • Sommaire
    → lecture dirigée
  • Index
    → tags / recherche plein texte

💡 Structures

  • Textes
  • Illustrations
  • Tags

💡 Primitives

  • Navigation architecturée / dirigée
  • Chapitrage
  • Index
  • Recherche plein texte

Les Quatre Fantastiques

Le manuel des Castors Juniors

  • résoud tout
  • toujours adapté
  • répond à tous les adverbes interrogatifs
    • où je trouve … ?
    • comment je fais … ?
    • quel est le … ?
    • pourquoi … ?

Comment c’est possible ?

La documentation parfaite n'existe pas

Vous allez devoir maintenir
4 documentations

1. README / Concepts

  • Apprentissage
  • Point de départ
  • Orienté pratique
  • Contenu rejouable à l’infini
  • expliquer
  • « Démarrer avec la plateforme »
  • « Utiliser le module d’internationalisation »
  • « Exécuter les tests »
  • « Afficher les statistiques d’utilisation »

2. How-to

  • Problèmes
  • Recettes / point précis
  • Dépendants du contexte
  • Flexibles et adaptables
  • démontrer
  • « Comment activer le 2FA »
  • « Comment configurer l’environnement de développement »
  • « Comment installer manuellement des extensions »
  • « Comment filtrer les requêtes entrantes »

3. Man pages

  • Information
  • Machinerie interne
  • Structure projet (code, features, etc.)
  • Contenus encyclopédiques
  • résoudre,
    explique les fondamentaux
NPM(1)                                                                    NPM(1)

NAME
       npm - javascript package manager

SYNOPSIS
         npm  [args]

VERSION
       6.11.3

DESCRIPTION
       npm  is  the  package manager for the Node JavaScript platform.  It puts
       modules in place so that node can find them, and manages dependency con‐
       flicts intelligently.

       It is extremely configurable to support a wide variety of use cases.
       Most commonly, it is used to publish, discover, install, and  develop
       node programs.

4. FAQs / Historique

  • Compréhension
  • Apporte du contexte
  • Répond aux questions
    sur le projet / features / etc.
  • Dogmatiques
  • compromis
  • « Puis-je ouvrir plusieurs comptes ? »
  • « Pourquoi blacklister ce provider ? »
  • « Quelles sont les limites d’espaces ? »
  • « Quelles sont les versions disponibles ? »

De l’organicité des contenus

  1. On n’est pas des machines
  2. On a besoin d’une structure
  3. Industrialiser la création

Si on ne range pas,
c’est le bordel !

4

README
Porte d'entrée
PratiqueHOW-TO
Recettes
ApprendreUtiliser
FAQs
Discussions
ComprendreMAN PAGES
Encyclopédique

C’est ça, le manuel
des Castors Juniors

Publier :
aux grands mots les bons outils

Deux objectifs

  • Documentation accessible
  • Contribution

Point d’entrée unique

  • Format textuel léger
  • Formatage simple
  • Facile à prendre en main
  • Facile à relire
  • Markdown (Mmark)
  • Asciidoc
  • reStructuredText
  • pandoc

Chaîne de production vers :

  • Web (HTML)
  • PDF
  • ePub

Vers le Web auto-hébergé
→ générateur statique

Notre exemple : Hugo
Notre exemple : Hugo
Learn Theme
Learn Theme

Vers le Web SaaS
→ Sphinx + ReadTheDocs

Vers PDF / ePub
→ Pandoc (ou LaTeX)

Contribution : dépôt de versions

  • Suivi de versions
  • Curation de contenus
    (Pull / Merge Requests)
  • Participatif

Éditeurs en ligne avec Git

  • Dillinger
  • StackEdit
  • Docsie

3 Questions

  1. Automatisation ?
  2. Internationalisation ?
  3. Bornage ?

Il n’y a pas de bon outil, ou de mauvais, il y a l’outil de votre cas d’usage

Plus de RTFM
Un guide rédactionnel

Incluez vos communautés

  • 4×4
  • Informez sur les bonnes pratiques
  • Curation (bienveillante)
  • Ne sur-estimez jamais le rôle de l’outil

Questions ?

Merci !


Disponible sous licence CC BY-SA 4.0

Illustrations

m4dz, CC BY-SA 4.0

Interleaf images

Courtesy of Unsplash and Pexels contributors

Icons

  • Layout icons are from Entypo+
  • Content icons are from FontAwesome

Fonts

  • Cover Title: Sinzano
  • Titles: Argentoratum
  • Body: Mohave
  • Code: Fira Code

Tools

Powered by Reveal.js

Source code available at
https://git.madslab.net/talks