ajout des conventions de forme
This commit is contained in:
parent
0927874cbf
commit
9db24ca2e5
19
Syntaxe.md
19
Syntaxe.md
|
@ -67,6 +67,8 @@ Pour afficher le "symbole" `/!\`, il est important d'échaper le dernier caract
|
||||||
|
|
||||||
## Conventions
|
## Conventions
|
||||||
|
|
||||||
|
### Conventions de syntaxe
|
||||||
|
|
||||||
Une commande lancée en root sera précédée de **#** ; en utilisateur elle sera précédée de **$**.
|
Une commande lancée en root sera précédée de **#** ; en utilisateur elle sera précédée de **$**.
|
||||||
Dans la mesure du possible, le maximum de commande devra être lancée en tant qu'utilisateur.
|
Dans la mesure du possible, le maximum de commande devra être lancée en tant qu'utilisateur.
|
||||||
|
|
||||||
|
@ -108,6 +110,23 @@ Par défaut on considère que l'on écrit de la documentation pour la version *s
|
||||||
> # aptitude install foo
|
> # aptitude install foo
|
||||||
> ~~~
|
> ~~~
|
||||||
|
|
||||||
|
### Conventions de forme
|
||||||
|
|
||||||
|
* Il doit y avoir des metadatas avec au minimum "categories" et "title"
|
||||||
|
* La 2ème 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
|
||||||
|
* Une section installation doit être présente. On considère que l'on est en Debian 9 par défaut, si besoin on précise les exceptions pour Debian 7 ou 8 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 / Plomberie / Monitoring / FAQ
|
||||||
|
* L'organisation des titres/sous-titres doit avoir une cohérence
|
||||||
|
* 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 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
|
||||||
|
|
||||||
|
À titre d'exemple, on pourra prendre le [HowtoApache]()
|
||||||
|
|
||||||
## Coloration syntaxique
|
## Coloration syntaxique
|
||||||
|
|
||||||
~~~
|
~~~
|
||||||
|
|
Loading…
Reference in a new issue