Différences

Ci-dessous, les différences entre deux révisions de la page.

--- wiki:recommandations [Le 19/03/2025, 07:15] – [Ligne éditoriale] krodelabestiole
+++ wiki:recommandations [Le 08/02/2026, 18:28] (Version actuelle) – +lien discussion https://forum.ubuntu-fr.org/viewtopic.php?id=2093942 krodelabestiole
@@ Ligne 10: / Ligne 10: @@
   * la page [[:wiki:syntaxe]]
   * et les [[:wiki:mini-tutoriels]].
+</note>
+<note tip>
+Pour discuter de ces recommandations, n'hésitez pas à participer à [[https://forum.ubuntu-fr.org/viewtopic.php?id=2093942|ce sujet]] sur le forum !
 </note>
 ===== Modèle général =====
-Roschan propose un très bon modèle pour documenter une nouvelle application sur sa page [[:utilisateurs:roschan:brouillon]].
+N'hésitez pas à utiliser des modèles comme point de départ de votre documentation.
-N'hésitez pas à l'utiliser comme point de départ de votre documentation.
-<note>copié collé de [[:wiki:participer_wiki#les_modeles]] : </note>
-Afin de garantir l'homogénéité du wiki, essayez, pour chaque page créée ou éditée, de conformer si possible vos contributions à l'un des [[wiki:modele|modèles proposés]] :
+Ils sont là : [[:wiki:participer_wiki#les modèles]].
-  * pour parler d'un logiciel, le modèle [[wiki:modeles:application|Application]] ;
-  * pour présenter un ordinateur, le modèle [[wiki:modeles:portable|Portable]] ;
-  * pour présenter un périphérique, le modèle [[wiki:modeles:materiel|Matériel]] ;
-  * pour des explications pas à pas, le modèle [[wiki:modeles:tutoriel|Tutoriel]] ;
-  * pour lister les ressources en lien avec une thématique, le modèle [[wiki:modeles:portail|Portail]] ;
-  * pour vous présenter sur le wiki, le modèle [[wiki:modeles:utilisateur|Utilisateur]].
-Si la page que vous projetez ne cadre pas avec l'un des modèles proposés, il vaut mieux poser la question aux autres contributeurs que de se lancer dans une adaptation libre, surtout pour une première contribution.
 ===== 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 économe en **liens internes**, c'est très utile !
-  * 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..."
+  * 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.
+  * Évitez de parler de la documentation sur la documentation : si celle-ci n'est pas à jour, dans la mesure du possible mettez-la à jour plutôt que d'écrire que "//les infos ne sont pas à jour//", svp ! C'est toujours mieux que rien, mais aucun autre contributeur ou administrateur ne devrait être censé passer derrière ce que chacun écrit. On peut utiliser ''%%FIXME%%'' (FIXME) surtout si on pense passer plus tard derrière, ou si on sait que l'information est fausse mais qu'on n'a pas les compétences qui permette la correction.
-  * Sur le web, **souligné** veut dire : lien. 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).
+  * Ne soyez pas avare en **[[:wiki:syntaxe#internes|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, de hors-sujet ou de répétition (cf. point //doublon// ou dessus). Il faut inviter autant que possible à la lecture, et ça se fait souvent en restant **concis**.
+  * Expliquez les lignes de commande ! Plutôt que :\\ //Entrer la commande ://\\ utilisez par exemple :\\ //Autoriser l'accès en écriture avec la commande ''[[man>chmod]]'' ://\\ Sans quoi les lignes de commande risquent d'être perçues comme des formules magiques, et n'aident pas les utilisateurs à gagner en autonomie.
+  * 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, ou qui sont trop techniques pour être utiles (les informaticiens utilisent en priorité la documentation officielle de chaque logiciel).
+  * Sur le web, **souligné** veut dire : __[[wpfr>Hyperlien|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 ayant un peu le rôle d'un sous-titre), ou éventuellement pour des noms de logiciels ou de protocoles (pour les chemins, les noms de paquets ou les commandes, 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, il ne propose pas le code de ces outils. Ce n'est pas une forge logiciel, il n'est pas 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 seulement le lien vers votre outil et éventuellement sa documentation sur le wiki.
 Ces recommandations valent pour les pages de documentation ordinaires.\\
@@ Ligne 47: / Ligne 43: @@
   * Consultez la [[https://www.dokuwiki.org/fr:wiki:syntax|documentation dokuwiki]] et utilisez les codes appropriés !
-  * ''apt install'' plutôt que ''apt-get install''
+  * ''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-cli|apt]]''.
+<note tip>
+Voir aussi [[:utilisateurs:krodelabestiole:brouillons:documentation|comment reconnaître une documentation moisie]] comme exemple de ce qu'il ne faut pas faire.
+</note>
 ==== 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]].
+==== Notes de bas de page ====
+<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 ====
+=== 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.
@@ Ligne 60: / Ligne 68: @@
 <code>''truc''</code>
 (plutôt que du gras ou de l'italique)
+=== Images ===
+Attention aux [[https://www.dokuwiki.org/fr:wiki:syntax#images_et_autres_fichiers|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 :
+<code>
+blabla, voir capture :
+{{:chemin:capture.png?400}}
+blabla
+</code>
+Tandis que les icônes des applications peuvent être flottantes sur la droite :
+<code>
+{{ :chemin:capture.png?80|icône de l'application}}
+==== Titre de l'application ====
+blabla
+</code>
+Ici après le ''?'' on a la largeur de l'image en pixels. Et après le ''|'', le contenu de l'attribut ''[[https://developer.mozilla.org/fr/docs/Web/HTML/Element/img#alt|alt]]'', affiché au survol de l'image, indispensable niveau accessibilité !
+=== Tableaux ===
+C'est la même chose pour les [[https://www.dokuwiki.org/fr:wiki:syntax#tableaux|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 !
+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 ces liens seul le contenu suivant le dernier '':'' ou ''#'' est affiché, la casse n'a pas d'importance, les ''_'' sont similaires aux espaces, et les accents et ponctuations sont supprimés, donc le //lien// [[:controleurs_midi]] ''%%[[:controleurs_midi]]%%'' est par exemple similaire à ''%%[[:Contrôleurs "MIDI"]]%%'' [[:Contrôleurs "MIDI"]] (ce qui évite souvent d'avoir à utiliser ''|'' pour rédiger un texte spécifique).
-  * 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.
@@ Ligne 92: / Ligne 128: @@
 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 spécifiquement orientée serveur (on utilise généralement SSH, et pas d'affiche graphique)
+  * 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''.
+... 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.
+===== Règles typographiques générales =====
+Ce sont des règles générales pour l'écriture du français. Il peut y avoir des différences en fonction des pays (pas d'espace avant '':'' en Suisse par ex.).
+==== Signes simples ====
+  * point ''.''
+  * virgule '',''
+  * points de suspension ''...'' (3 points ''%%...%%'' sont remplacés par le caractère ''...'' automatiquement)
+//Signe simple, espace simple// : on met une espace après le signe, pas avant.
+==== Signes doubles ====
+  * deux-points '':''
+  * point-virgule '';''
+  * point d'exclamation ''!''
+  * point d'interrogation ''?''
+//Signe double, espace double// : une espace avant et une espace après.
+==== Autres ====
+Parenthèses ''( )'' et guillemets droits ''%%" "%%'' : espaces à l'extérieur, mais pas à l'intérieur.\\
+Exception : pas d'espace entre la parenthèse finale et le signe simple qui suit.
+Guillemets à l'anglaise ''“ ”'' : comme les guillemets droits.\\
+Guillemets à la française ''« »'' : comme les signes doubles.\\
+Ces signes sont plutôt littéraires et alourdissent les pages de ce wiki inutilement, on peut généralement se contenter des guillemets droits.
+Pareil pour les apostrophes : inutile d'utiliser les apostrophes littéraires ''’'', le guillemet simple ''%%'%%'' (aussi appelé apostrophe droite) va très bien et prend moins de place !((cf [[wpfr>Guillemet#Codage]]))
+(et pas d'espace autour !).
+-----
+  * [[https://forum.ubuntu-fr.org/viewtopic.php?id=2093942|Discussion]] au sujet de cette page sur le forum.
+  * //[[:Contributeurs]] : [[:utilisateurs:krodelabestiole]].//

Différences

Outils pour utilisateurs

Outils du site

Outils de la page

Divers