Table des matières

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.

Voir aussi et surtout :

Modèle général

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

Ils sont là : les modèles.

Ligne éditoriale

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).

Techniquement

Voir aussi comment reconnaître une documentation moisie comme exemple de ce qu'il ne faut pas faire.

Mini tutoriels

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

Notes de bas de page

((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://…]].

Mise en forme

Code en ligne

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)

Images

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é !

Tableaux

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

Liens adaptés

utilisez des liens adaptés, voir documentation dokuwiki !

Application web

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.

Versions

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.

Tags

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

Lignes de commande

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

… et en particulier quand elle fait intervenir sudo.