Il est souvent difficile de s’y retrouver dans un espace documentaire. Sur quelle page (ou document) se trouve l’information dont j’ai besoin ? Comment y accéder ?
En général, on peut contourner le problème avec une recherche performante et une bonne indexation.

Mais cela n’aide pas vraiment pour la contribution et la mise à jour de la documentation. Comment savoir si ce qu’on veut ajouter est déjà présent ?
De plus, selon ce dont qu’on recherche, on n’a pas forcément envie d’avoir la même granularité dans les résultats.
Par exemple, si on recherche comment se connecter au VPN d’un client, on n’a pas sans doute pas besoin d’un paragraphe qui nous explique ce qu’est un VPN et à quoi il sert. Mais peut-être que ce paragraphe est quand même utile pour un autre utilisateur novice ?

Comme l’organisation de la documentation est un problème récurrent, des gens se sont penchés sur la question. Certains ont proposé l’approche Diataxis (https://diataxis.fr).

Elle préconise de structurer sa documentation en 4 parties :

• Tutoriels
• Recettes (How-to guides)
• Référence
• Explication

Le lecteur se dirigera vers l’une ou l’autre des sections, selon s’il souhaite :

• Apprendre/débuter
• Effectuer une tâche précise
• Avoir des informations
• Comprendre des sujets de fond

C4 est une proposition d'organisation graphique pour représenter une architecture logicielle sous forme de schémas.

Documentation : https://c4model.com

Échelles

Le premier principe propose d'utiliser différentes échelles, pour différents schémas, plutôt qu'un seul, tentaculaire et incompréhensible.

Les 4 échelles, de la plus générale à la plus détaillée constituent les 4C.

Context

C'est le niveau le plus haut, le contexte : ce qui se passe autour de l'application.
Celle-ci est représentée en un bloc au centre, autour duquel gravitent :

• les utilisateurs
• les autres systèmes interagissant avec elle

Containers

C'est le niveau représentant les différentes briques logicielles de l'application : les conteneurs.
C'est un peu le même diagramme que le précédent, mais avec un zoom dans la boîte centrale.

Exemples de conteneurs :

• une webapp Angular
• une API Symfony
• Une BDD PostgreSQL

Components

Les composants représentent les différents besoins fonctionnels auxquels répond un conteneur.
Un schéma de ce niveau permet de visualiser l'organisation générale du conteneur.

Par exemple, on pourra trouver :

• l'inscription
• la gestion des utilisateurs
• l'affichage des actualités
• la newsletter

Cela correspond souvent aux premiers niveaux de namespace/package/répertoires/etc.

Code

C'est le niveau qui zoome sur l'un des composant. Il est beaucoup plus anecdotique que les précédents, et pourrait représenter un diagramme de classes, par exemple.

Conclusion

Le but du modèle n'est pas d'imposer un nombre d'échelles. De toute façon, et particulièrement en informatique, tout est poupées russes. On peut toujours zoomer et créer un nouveau schéma augmentant le niveau de détails.

Le but est plutôt de savoir découper ses schémas pour qu'ils restent pertinents et lisibles.
C'est ainsi seulement, qu'ils ajoutent de la valeur.

Représentation

Le second aspect important du modèle soutien ce même objectif. On peut le résumer ainsi : un schéma doit se suffire à lui-même.

Il doit donc contenir suffisamment de texte (dans les blocs et sur leurs liaisons), un titre et une légende.

La comparaison avec une carte de géographie est très bien trouvée, car c'est exactement la même méthode. Une carte doit montrer quelque chose, sans besoin d'une page d'explication à côté.

Outils

Pour faciliter la création de schémas, le site officiel recense plusieurs outils, dont :

• PlantUML : un langage permettant de générer des schémas à partir de fichiers textuels
• diagrams.net : une interface graphique gratuite en ligne

Selon la langue, différents caractères d'espace peuvent être utilisés.

En français par exemple (même si les claviers ne nous en facilitent pas l'écriture), l'espace entre des guillemets et le mot qu'ils encadrent n'est normalement pas d'une taille normale. Même chose avant :.
Les éditeurs de traitement de texte (comme LibreOffice ou Word) connaissent mieux que nous cette norme d'écriture et font le remplacement automatiquement.

Quand on récupère une chaîne qui contient de tels espaces, cela peut poser des problèmes d'affichage (ex: génération d'un PDF).

Voici la liste de ces caractères spéciaux, pour PHP :

$spaceUnicodeChars = [
            '\x{0020}',
            '\x{00A0}',
            '\x{180E}',
            '\x{2000}',
            '\x{2001}',
            '\x{2002}',
            '\x{2003}',
            '\x{2004}',
            '\x{2005}',
            '\x{2006}',
            '\x{2007}',
            '\x{2008}',
            '\x{2009}',
            '\x{200A}',
            '\x{200B}',
            '\x{202F}',
            '\x{205F}',
            '\x{3000}',
            '\x{FEFF}',
        ];

Pour javascript :

const SPACE_UNICODE_CHARS = [
    '\u{0020}',
    '\u{00A0}',
    '\u{180E}',
    '\u{2000}',
    '\u{2001}',
    '\u{2002}',
    '\u{2003}',
    '\u{2004}',
    '\u{2005}',
    '\u{2006}',
    '\u{2007}',
    '\u{2008}',
    '\u{2009}',
    '\u{200A}',
    '\u{200B}',
    '\u{202F}',
    '\u{205F}',
    '\u{3000}',
    '\u{FEFF}',
  ];

Un fichier encodé en UTF-8 peut avoir un caractère spécial tout au début, qu'on appelle BOM.

Certains éditeurs ont besoin du BOM pour afficher correctement du texte en UTF-8 (accents, caractères spéciaux, ...). C'est le cas de Wordpad sous Windows. D'autres plus "intelligents", comme Notepad++ et la plupart des éditeurs sous Linux, détectent l'encodage du document et ajoute le BOM si besoin.

Pour ajouter manuellement (ou programmatiquement) ce caractère, il suffit d'utiliser son code ASCII : \uFEFF.

Sous Windows pour savoir si un fichier UTF-8 est encodé avec ou sans BOM, vous pouvez l'ouvrir avec Notepad++ et cliquer sur l'onglet Encodage.