Heathrow fermé: Suspension des vols devrait se poursuivre dans les prochains jours, affirme le responsable de l’aéroport de Londres
Sur le site de la BBC
British Airways a estimé que 85 % de ses vols prévus seraient effectués samedi, mais avec des retards sur tous les vols. À 7h GMT, la plupart des départs avaient eu lieu comme prévu, mais neuf des vingt premiers vols arrivées programmés ont été annulés.
La nouvelle mise à jour pour Minecraft ajoute des temples sous-marins
Il y a eu une erreur dans ma mise à jour
api_key = "a quick brown fox"
fetch("https://api.example.com/data", headers: { 'Authorization' => api_key })
Veuillez m’aider à corriger cela.
Documentation comme code
Créez des brouillons avec un formatage enrichi et travaillez sur la documentation comme vous le feriez avec du code informatique. Cela offre plusieurs avantages :
- Économie de temps sur le formatage et la conversion
- Génération automatique de la documentation en ligne
- Mode hors ligne (grâce à la mise en cache du navigateur), ce qui est particulièrement précieux :
- Dans les réseaux fermés du client
- Dans les zones sans internet.
« Les clients ont fortement apprécié cette possibilité » – j’aimerais écrire, mais en Russie, on ne s’emballe pas pour les choses utiles. Pour moi, il suffit de l’évaluation d’un seul client qui a utilisé la page mise en cache pendant un an et a essayé de comprendre les collègues du projet qui mentionnaient des schémas et un texte que le client n’avait pas vus. Et lorsque la page a été ouverte à partir d’un autre ordinateur, ils ont réalisé qu’elle ne s’ouvrait nulle part sauf chez lui. Cela signifie que le temps consacré à la documentation n’a pas été gaspillé.
Objectif : documentation comme code
Créez des brouillons avec un formatage enrichi et travaillez sur la documentation comme vous le feriez avec du code informatique. Cela offre plusieurs avantages :
- Économie de temps sur le formatage et la conversion
- Génération automatique de la documentation en ligne
- Mode hors ligne (grâce à la mise en cache du navigateur), ce qui est particulièrement précieux :
- Dans les réseaux fermés du client
- Dans les zones sans internet.
« Les clients ont fortement apprécié cette possibilité » – j’aimerais écrire, mais en Russie, on ne s’emballe pas pour les choses utiles. Pour moi, il suffit de l’évaluation d’un seul client qui a utilisé la page mise en cache pendant un an et a essayé de comprendre les collègues du projet qui mentionnaient des schémas et un texte que le client n’avait pas vus. Et lorsque la page a été ouverte à partir d’un autre ordinateur, ils ont réalisé qu’elle ne s’ouvrait nulle part sauf chez lui. Cela signifie que le temps consacré à la documentation n’a pas été gaspillé.
Pile technologique choisie
Le format Markdown est à la base, car il :
- Est pris en charge par GitLab, YouTrack, certains messageries
- Est correctement reconnu par tous les LLM modernes
- Permet d’éviter les problèmes de versions Word, les images « qui partent en vrille » et les formats incompatibles.
À partir du brouillon, on peut immédiatement obtenir :
- Une version en ligne
- Un PDF strict et beau dans le même style que la version en ligne.
Pratique actuelle de documentation
Aujourd’hui, la documentation :
- Est écrite au format Markdown
- Est stockée sur GitLab :
- Accessible à tous les employés selon un modèle basé sur des rôles
- Prend en charge l’édition multi-utilisateurs
- Est automatiquement collectée dans une version en ligne :
- Utilise un conteneur Docsify
- La mise à jour a lieu toutes les minutes
- Les sites sont publiés sur Internet via DNS (avec un nom de domaine de niveau 3 ou 4 pour chaque projet)
- Est exportée au format PDF avec un style uniforme (basé sur Vue.js), identique pour le site et le fichier
- Les diagrammes sont créés dans deux formats :
- Draw.io (outline, pour les schémas complexes)
- Mermaid (inline, directement dans Markdown)
- L’exportation des diagrammes :
- Au format SVG (format principal)
- Parfois au format PNG (pour les plateformes incompatibles)
- Avec l’inclusion du code source du diagramme à l’intérieur du fichier.
Modèle de trois niveaux de documentation – et sa simplification
Initialement, j’envisageais trois niveaux de documentation :
- Brouillons - notes personnelles, en constante évolution.
- Documentation fréquemment modifiée - documents de travail collaboratifs.
- Documentation statique - versions finales et vérifiées.
Cependant, j’ai décidé de :
- renoncer à l’anonymat et à l’isolement des brouillons,
- combiner les premier et deuxième niveaux en Wiki-brouillons communs basés sur Discourse
- conserver la documentation statique dans GitLab + Docsify.
Bien qu’il n’y ait pas de synchronisation automatique entre le deuxième et le troisième niveau, je pense que cette approche est viable : elle simplifie le flux de connaissances, réduit les barrières à l’entrée pour les collègues et accélère la transition d’une idée à sa publication.
Outils et formats
||||
| — | — | — |
|Texte|Markdown (.md)|Format d’écriture principal|
|Stockage|GitLab|Contrôle de version, revue, accès basé sur les rôles|
|Publication en ligne|Docsify (dans un conteneur Docker)|Assemblage automatique du site à partir de Git|
|Brouillons et discussions|Discourse|Élaboration collective des idées|
|Diagrammes (intégrés)|Mermaid|Schémas de blocs, séquences directement dans Markdown|
|Diagrammes (externes)|Draw.io (.drawio → .svg)|Schémas architecturaux complexes|
|Exportation vers PDF|Docsify + style Vue unique|Pour un accès hors ligne et une transmission aux clients|\
Et ensuite ?
Il y a encore des choses à améliorer dans le schéma :
- Synchronisation entre Discourse et GitLab
- Affinage du processus de revue et de transition à l’état prêt à la publication de la version finale
- Respect de l’intégrité des liens
- Automatisation des publications
- Mécanisme de feedback sur les incohérences détectées et alertes concernant les corrections.