diff --git a/Syntaxe.md b/Syntaxe.md index 19fb9375..670a7861 100644 --- a/Syntaxe.md +++ b/Syntaxe.md @@ -104,9 +104,9 @@ Pour relancer un service : `/etc/init.d/foo restart` OU `systemctl restart foo`. Pour installer un paquet sous Debian, on utilise la commande `apt` → `apt install foo`. -Par défaut on considère que l'on écrit de la documentation pour la version *stable* d'OpenBSD ou pour *Debian 9*. Des remarques **obligatoires** doivent être faites pour *Debian 8*. Des remarques éventuelles peuvent être faites pour les version précédentes (Debian 7, etc). Ces remarques devraient être mises sous forme de "notes" du type : +Par défaut on considère que l'on écrit de la documentation pour la version *stable* d'OpenBSD ou de Debian. Des remarques **obligatoires** doivent être faites pour Debian *oldstable*. Des remarques éventuelles peuvent être faites pour les version précédentes (*oldoldstable*, *oldoldoldstable*, etc). Ces remarques devraient être mises sous forme de "notes" du type : -> *Note* : Pour Debian 7 et 8, on peut faire : +> *Note* : Pour Debian 8 et 9, on peut faire : > > ~~~ > # aptitude install foo @@ -114,24 +114,24 @@ Par défaut on considère que l'on écrit de la documentation pour la version *s ### Conventions de forme -* Il doit y avoir des metadatas avec au minimum "categories" et "title" -* La 2e ligne de la documentation doit être un choix réfléchi de catégories en fonction des catégories déjà existantes -* Si une documentation officielle existe, elle doit être notée tout en haut sous la forme : Documentation : -* Si un rôle Ansible existe, il doit être noté avec le lien vers la branche stable sur la forge sous la forme : Rôle Ansible : +* Il doit y avoir des metadatas avec au minimum "categories" et "title". +* La 2e ligne de la documentation doit être un choix réfléchi de catégories en fonction des catégories déjà existantes. +* Si une documentation officielle existe, elle doit être notée tout en haut sous la forme : `Documentation : `. +* Si un rôle Ansible existe, il doit être noté avec le lien vers la branche stable sur la forge sous la forme : `Rôle Ansible : `. * La description doit être succinte (entre 3 et 10 lignes) ET subjective d'un point de vue Evolix -* Un lien vers le site officiel doit être positionné sur la 1ère occurence du nom de la techno dans la description. -* Une section installation doit être présente. On considère que l'on utilise la dernière version de Debian et/ou d'OpenBSD par défaut, si besoin on précise les exceptions pour des releases précédentes comme précisé plus haut -* Dans la section installation, on montrer la commande apt d'installation, mais un moyen d'obtenir la version installée en temps qu'utilisateur non-root et l'état de l'éventuel démon avec sysctemctl status SAUF la ligne "active" -* En général, il doit y avoir au moins les titres : Installation / Configuration / Administration / Optimisation / Plomberie / Monitoring (avec sous-titres Munin et Nagios) / FAQ -* L'organisation des titres/sous-titres doit être cohérente quand on regarde la table des titres -* Les conventions de syntaxe doivent être appliquées partout (voir ci-dessous) notamment pour les adresses IP, les "Note :", les fichiers sous la forme `/etc/foo.conf` etc. -* Les exemples de code ou contenu de fichiers doivent utiliser la syntaxe avec trois tildes -* Si l'on mentionne des autres documentations, mettre des liens internes -* Objectif 0 faute d'orthographe / de grammaire -* Tout ce qu'on a mis en production sur des serveurs doit être mentionné -* Quand on mentionne des commandes avec des arguments, il faut mettre les versions longues (exemple: `--dry-run` au lieu de `-d` si possible) -* Si la doc est longue, on hésitera pas à avoir un titre "Configuration de base" et "Configuration avancée", ou alors un sous-titre "Utilisation de base" avec les commandes de base si l'on doit lire la doc en 1 minute -* Si la doc est très longue, elle peut être découpée en sous-pages à l'exemple du [HowtoMySQL]() +* Un lien vers le site officiel doit être positionné sur la 1ère occurence du nom de la techno dans la description. +* Une section installation doit être présente. On considère que l'on utilise la dernière version de Debian et/ou d'OpenBSD par défaut, si besoin on précise les exceptions pour des releases précédentes comme précisé plus haut. +* Dans la section installation, on montrer la commande apt d'installation, mais un moyen d'obtenir la version installée en temps qu'utilisateur non-root et l'état de l'éventuel démon avec sysctemctl status SAUF la ligne "active". +* En général, il doit y avoir au moins les titres : Installation / Configuration / Administration / Optimisation / Plomberie / Monitoring (avec sous-titres Munin et Nagios) / FAQ. +* L'organisation des titres/sous-titres doit être cohérente quand on regarde la table des titres. +* Les conventions de syntaxe doivent être appliquées partout (voir ci-dessous) notamment pour les adresses IP, les "Note :", les fichiers sous la forme `/etc/foo.conf`, etc. +* Les exemples de code ou contenu de fichiers doivent utiliser la syntaxe avec trois tildes. +* Si l'on mentionne d’autres documentations, mettre des liens internes. +* Objectif zéro faute d'orthographe ou de grammaire. +* Tout ce qu'on a mis en production sur des serveurs doit être mentionné. +* Quand on mentionne des commandes avec des arguments, il faut mettre les versions longues (exemple: `--dry-run` au lieu de `-d` si possible). +* Si la doc est longue, on hésitera pas à avoir un titre "Configuration de base" et "Configuration avancée", ou alors un sous-titre "Utilisation de base" avec les commandes de base si l'on doit lire la doc en 1 minute. +* Si la doc est très longue, elle peut être découpée en sous-pages à l'exemple du [HowtoMySQL](). À titre d'exemple, on pourra prendre le [HowtoApache]()