Recommandations concernant le Wiki ubuntu-fr

Cette page se propose de compléter le chapitre des bonnes pratiques pour la rédaction de la documentation ici présente, et de partager les décisions prises en particulier sur la mailing list concernant des points particuliers de la ligne éditoriale.

N'hésitez pas à utiliser des modèles comme point de départ de votre documentation.

Ils sont là : les modèles.

• Évitez le prosélytisme ! pas de "embellissez votre vie grâce à systemd…". Si un logiciel est bon, sa simple description factuelle suffira à motiver son adoption. Assez de pub autour de nous, faites confiance à l'intelligence des lecteurs !
• Pas de doublon : mettez un lien vers la page ou le chapitre le plus adapté, où sera le mieux détaillé ce dont vous avez besoin ! Ça facilite la maintenance et donne accès à un maximum d'infos.
• Ne soyez pas avare en liens internes, c'est très utile pour apprendre le vocabulaire et comprendre l'articulation de l'informatique !
• Allez droit au but, pas de remplissage pour le remplissage ou de répétition. Il faut inviter au maximum à la lecture, et ça se fait souvent en restant concis.
• N'utilisez pas la première personne, ni pour parler de votre expérience personnelle (le wiki n'est pas un journal personnel), ni pour déposséder le lecteur de son identité !
• Si votre avis ou votre méthode ne fait pas consensus, prenez-le en compte en l'indiquant par ex. par "selon certains avis…"
• Quand ils ne sont pas strictement nécessaires, évitez de coller les retours de commande en exemple qui donnent à voir un système particulier, qui ne correspond pas à celui du lecteur.
• Sur le web, souligné veut dire : lien. À éviter pour faire ressortir du texte qui n'en est pas un donc ! Pour mettre du texte en valeur utilisez plutôt les <note> si il est long, sinon l'italique (on parle d'emphase). Le gras sert à faire ressortir le sujet d'un paragraphe, comme ici (en remplaçant par ex. un sous-titre), ou éventuellement pour des noms de logiciels (pour les noms de paquets, mieux vaut utiliser '').
• Ne documentez pas un logiciel que vous ne maîtrisez pas ou mal. On trouve beaucoup d'erreurs ou de mauvaises méthodes sur le web, mieux vaut parfois ne rien faire que de les relayer.
• Évitez d'inclure des scripts sur les pages ! Le wiki est une documentation, sur comment utiliser des outils, ce n'est pas le code de ces outils, ce n'est pas une forge logiciel et ce n'est pas un outil adapté à la révision par les pairs et la maintenance du code. Si vous avez du code à partager, utile pour ubuntu, partagez-le sur une forge (gittea, gitlab, framagit, launchpad…) et postez un lien vers votre outil sur le wiki.

Ces recommandations valent pour les pages de documentation ordinaires.
Chacun fait par contre ce qui lui plaît dans les pages de son espace personnel (vous pouvez y tenir un journal de développement si vous le souhaitez).

• Consultez la documentation dokuwiki et utilisez les codes appropriés !
• apt install plutôt que apt-get install.
• Attention à la casse (minuscules / majuscules) de certains noms ou sigles ! Par ex. ne pas confondre APT et apt.

Utilisez les mini tuto, pour l'installation, désinstallation de logiciels depuis tout format, ou de PPA ! C'est là : mini-tutoriels.

((Note de bas de page))

Cette double parenthèse permet de créer une note de bas de page. Elle permet justement de garder la page claire et simple, sans partir dans tous les sens. Très utile pour les voir aussi, ou les liens vers wikipedia [[wpfr>… quand on a déjà mis un lien interne [[:… ou vers le site officiel [[https://…]].

Pour tout ce qui est nom de paquet, commande courte ou court extrait de code, nom ou valeur de variable, chemin, etc. comme ça :

''truc''

(plutôt que du gras ou de l'italique)

Attention aux images : les espace après {{ ou avant }} ont leur importance pour définir l'alignement de l'image !

On veut généralement que les illustrations (captures, schémas, …) soient alignées à gauche, mais non flottantes, comme le reste du texte. Donc sans espace entre les {{}} mais avec un saut de ligne avant et après :

blabla, voir capture :

{{:chemin:capture.png?400}}

blabla

Tandis que les icônes des applications peuvent être flottantes sur la droite :

{{ :chemin:capture.png?80|icône de l'application}}
==== Titre de l'application ====

blabla

Ici après le ? on a la largeur de l'image en pixels. Et après le |, le contenu de l'attribut alt, affiché au survol de l'image, indispensable niveau accessibilité !

C'est la même chose pour les tableaux : attention aux espace avant ou après | qui déterminent l'alignement du texte !

utilisez des liens adaptés, voir documentation dokuwiki !

• Utilisez des liens internes avec

  [[:lien]]

  ou

  [[:tutoriel:page]]

  Ce n'est pas indiqué sur la doc officielle mais commencer par : permet de rendre le chemin absolu, donc fonctionnel depuis partout.

• Pour les articles wikipedia :

  [[wpfr>article]]

• Pour l'installation des paquets :

  ''[[apt>paquet]]''

• [[https://]]

  est à réserver au forum et aux sites exotiques.

Si elle existe évitez de documenter uniquement l'installation via paquet APT qui n'est souvent pas à jour.

Si l'application requiert un serveur lamp, vous pouvez suivre le modèle de la page WordPress.

On documente en priorité les deux dernières versions LTS.

La documentation spécifique à des versions qui ne sont plus supportées doit être supprimée.

On indique les versions par leur nom de code et leur numéro de version, avec un lien vers la page qui leur est dédiée, par ex. : Bionic 18.04.

On indique dans les tags les versions LTS concernées par la doc, seulement par leur nom de code.

Il est recommandé d'éviter d'indiquer uniquement la ligne de commande (il vaut mieux apprendre à pêcher…), excepté dans certaines circonstances :

• restauration de l'affichage graphique (évidemment)
• documentation d'un outil en ligne de commande (dans ce cas on peut quand-même proposer des alternatives en bas de page)
• documentation spécifiquement orientée serveur (on utilise généralement SSH, et pas d'interface graphique)
• pas d'alternative graphique existante

… et en particulier quand elle fait intervenir sudo.

• Dans tous les cas ne jamais présenter des commandes sans expliquer indépendamment ce qu'elles font.