parent
bc15788cae
commit
b87b85ebae
38
Syntaxe.md
38
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 : <lien>
|
||||
* 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 : <lien>
|
||||
* Il doit y avoir des metadatas avec au minimum "categories" et "title".
|
||||
* La 2<sup>e</sup> 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 : <lien>`.
|
||||
* 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 : <lien>`.
|
||||
* 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<sup>ère</sup> 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]()
|
||||
|
||||
|
|
Loading…
Reference in a new issue