Différences
Ci-dessous, les différences entre deux révisions de la page.
| Les deux révisions précédentes Révision précédente Prochaine révision | Révision précédente | ||
|
wiki:recommandations [Le 19/03/2025, 14:21] krodelabestiole suppr doublon modèles / +conseils mise en forme images / tableaux |
wiki:recommandations [Le 14/04/2025, 11:55] (Version actuelle) krodelabestiole [Ligne éditoriale] reformulations |
||
|---|---|---|---|
| Ligne 20: | Ligne 20: | ||
| ===== Ligne éditoriale ===== | ===== Ligne éditoriale ===== | ||
| - | * É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 ! | + | * Évitez le **prosélytisme** ! pas de "//embellissez votre vie grâce à systemd...//". Si un logiciel est utile et bon, sa simple description factuelle suffit à motiver son adoption. Assez de pub autour de nous, faites confiance à l'intelligence et au jugement des lecteur·rice·s ! |
| - | * 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. | + | * Pas de **doublon** (ou pire) : si il existe une page ou un chapitre plus appropriée détaillant déjà votre sujet, il est beaucoup plus judicieux de les mettre en lien que de se répéter, même succinctement ! Ça donne accès aux internautes à un maximum d'infos et pour les contributeurs c'est le seul moyen de rendre possible la maintenance globale du wiki.((C'est en particulier le cas pour les procédures répétitives et systématiques, voir [[:wiki:mini-tutoriels|mini-tutos]].)) |
| * Ne soyez pas avare en **liens internes**, c'est très utile pour apprendre le vocabulaire et comprendre l'articulation de l'informatique ! | * 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**. | * 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**. | ||
| Ligne 29: | Ligne 29: | ||
| * 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 ''%%''%%''). | * 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. | * 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.\\ | Ces recommandations valent pour les pages de documentation ordinaires.\\ | ||
| Ligne 45: | Ligne 46: | ||
| ==== Mini tutoriels ==== | ==== Mini tutoriels ==== | ||
| - | Utilisez les mini tuto, pour l'installation, désinstallation de logiciels depuis tout format ou de PPA ! | + | Utilisez les mini tuto, pour l'installation, désinstallation de logiciels depuis tout format, ou de PPA ! |
| C'est là : [[:wiki:mini-tutoriels]]. | C'est là : [[:wiki:mini-tutoriels]]. | ||
| ==== Notes de bas de page ==== | ==== Notes de bas de page ==== | ||
| - | <code>((Note de bas de page))</code> permet de créer une note de bas de page. Ça 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://%%...]]''. | + | <code>((Note de bas de page))</code> |
| + | 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 ==== | ==== Mise en forme ==== | ||
| Ligne 91: | Ligne 93: | ||
| ==== Liens adaptés ==== | ==== Liens adaptés ==== | ||
| - | utilisez des liens adaptés, voir documentation dokuwiki ! | + | utilisez des [[https://www.dokuwiki.org/fr:wiki:syntax#liens|liens]] adaptés, voir [[https://www.dokuwiki.org/fr:wiki:syntax#liens|documentation dokuwiki]] ! |
| - | * utilisez des liens internes avec <code>[[:lien]]</code> ou <code>[[:tutoriel:page]]</code> | + | * Utilisez des liens internes avec <code>[[:lien]]</code> ou <code>[[:tutoriel:page]]</code>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 : <code>[[wpfr>article]]</code> | + | * Pour les articles wikipedia : <code>[[wpfr>article]]</code> |
| - | * pour l'installation des paquets :<code>''[[apt>paquet]]''</code> | + | * Pour l'installation des paquets :<code>''[[apt>paquet]]''</code> |
| * <code>[[https://]]</code> est à réserver au forum et aux sites exotiques. | * <code>[[https://]]</code> est à réserver au forum et aux sites exotiques. | ||
| Ligne 120: | Ligne 122: | ||
| Il est recommandé d'éviter d'indiquer uniquement la ligne de commande (il vaut mieux apprendre à pêcher...), excepté dans certaines circonstances : | 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) | * 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) | * documentation spécifiquement orientée serveur (on utilise généralement SSH, et pas d'interface graphique) | ||
| * pas d'alternative graphique existante | * pas d'alternative graphique existante | ||
| Ligne 125: | Ligne 128: | ||
| ... et en particulier quand elle fait intervenir ''sudo''. | ... 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. | + | * Dans tous les cas ne jamais présenter des commandes sans **expliquer** indépendamment ce qu'elles font. |