De l'évolution de la documentation

Un constat que je fais depuis un certain temps déjà est que la documentation devient de plus en plus difficile à maintenir, et que le nombre de pages qui vont devenir vétustes par manque de temps ou par manque de nécessité de les mettre à jour (programmes simples à utiliser ou ne n'ayant pas eu de mise à jours / nouvelles fonctions par exemple). De plus on oublie souvent le fait que l'on n'écrit pas uniquement de la documentation pour l'environnement Gnome, mais également xFce, KDE 4.x et UNR/Moblin. Je ne suis pas utilisateur KDE, mais je pense qu'ils doivent se sentir un peu "isolés" dans la documentation, malgré leurs thèmes spécifiques.

En fait c'est simple et compliqué à la fois, il serait marrant/intéressant/idéal que lorsque l'on se trouve sous doc.ubuntu-fr.org on ne retrouve que le mot "ubuntu" lorsqu'il s'agit d'une référence à notre distribution, ce même mot serait remplacé automatiquement par "kubuntu" sur doc.kubuntu-fr.org, et "xubuntu" sur doc.xubuntu-fr.org .

Je ne sais pas si c'est réalisable et cela impliquerait de remplacer ces références "ubuntu" par quelque chose du type distribution qui serait remplacé automatiquement.

Inutile si on se limite aux mots "Ubuntu", Kubuntu" etc. Il faut élargir l'idée a des paragraphes entiers (texte+captures), ce qui me parait une bonne idée à priori, mais compliquera la comprehension/edition de la source des pages pour les nouveaux contributeurs. — YannUbuntu 2009/07/06 09:37

La c'est mon esprit tordu qui imagine ça, mais il serait aussi agréablement intéressant pour les utilisateurs enregistrés qui auraient renseigné la version sur laquelle ils tournent dans leur profil, qu'ils n'aient que les informations relatives à cette version d'afficher sur une page. Cela impliquerait encore un niveau complémentaire de balises dans les pages à savoir inventer un tag <version 9.04>texte relatif à cette version</version>. Ces blocs seraient donc masqués et affichables d'un simple clic sur un lien. On pourrait voir en début de page quelque chose du style

affiche: 8.04 / 8.10 / **9.04** / Tout

La aussi il s'agit d'ajouter une syntaxe de filtrage par blocs. remarques idem filtrage d'environnement. — YannUbuntu 2009/07/06 09:37

Cette fonction serait un bouton supplémentaire qui serait présent sur toutes les pages qui n'ont pas pour tag la dernière version d'ubuntu (Jaunty en ce moment). Le principe serait de pouvoir lire une page, si elle est encore adéquate on valide juste avec ce bouton qui ajouterait le tag complémentaire sans besoin d'éditer la page et de l'enregistrer.

ok, si cette fonction est accessible uniquement par un utilisateur enregistré. — YannUbuntu 2009/07/06 09:37

Un autre point qu'il serait intéressant de rapprocher avec la doc c'est toute la documentation déjà existante et disponible sur notre système.

Les paquets d'abords sont une source d'information idéale (nom du paquet pour le nom de la page de documentation, description, nom du programme, site web officiel éventuellement). Il serait intéressant que les programmes accessibles par l'installateur "ajouter/supprimer…" et qui n'ont pas de page de documentation en ait une générée automatiquement avec ces informations de base, une structure simple de page (installation, configuration, liens).

On pourrait même pousser le raisonnement plus loin en imaginant que toutes les pages, même celles existantes possèdent ce lien étroit avec les paquets, cela permettrait peut être d'accélérer/améliorer la traduction/description de ces éléments. Cette structure complète pourrait être intégrée avec juste une balise du type search?q=%20nom_du_paquet&amp;btnI=lucky

On pourrait imaginer pour la création de nouvelles pages une série de questions pour orienter le rédacteur et créer automatiquement un squelette de page contenant déjà toutes les informations classiques "titre, description, …".

Me parait indispensable pour faciliter le travail des nouveaux contributeurs ! — YannUbuntu 2009/07/06 09:37

Un énorme soucis avec la politique actuelle de tout mettre à la racine, relativement aux ACL, est que l'on ne peut pas empêcher la création de nouveaux namespaces. Je pense qu'il faut limiter la création aux personnes non connectées, ne serait-ce que pour un soucis de contact des primo autores des pages. et bon si les anonymes peuvent pas créer, et bien, on peut toujours taper sur les doigts des inscrits qui ont pas lu les règles

Tout le monde est daccord pour ajouter un lien dans le menu de gauche vers la page expliquant comment participer à la doc.

De même pour le remplacement du lien de l'énorme archive du wiki par un lien vers la page qui parle de la documentation hors ligne, page à modifier en conséquence.

ok. — YannUbuntu 2009/07/06 09:37

J'en profite pour rajouter un lien vers la page de téléchargement d'ubuntu, après tout quand on cherche une info sur gnu/linux on tombe très souvent sur les pages de la documentation d'ubuntu, autant inciter les gens à l'essayer ;)

on devrait avoir le portail "Telecharger Ubuntu" dans la nouvelle page d'accueil de la Doc. — YannUbuntu 2009/07/06 09:37

• ACL – fournit par défaut, permet de gérer graphiquement les contrôles d'accès sur les pages. Je pense qu'il est utile mais en même temps je pense qu'il ne faut surtout pas l'utiliser et préférer l'usage de l'édition du fichier de conf directement que l'on commit/push avant d'appliquer afin de garder une traçabilité.
• backlinks – permet de lister les pages qui pointent sur une page donnée. On garde, toujours utile pour les suppressions/déplacement. Une évolution possible serait de permettre de lister les pages pointant sur une page non existante.

indispensable. — YannUbuntu 2009/07/06 09:37

• cloud – Permet de faire un nuage des mots les plus utilisés sur le wiki (on ne s'en sert pas), et surtout un nuage des tags utilisés également (mais est-ce qu'on s'en sert vraiment?).
  Perso je pense que ce plugin ne sert pas à grand chose actuellement et qu'on peux tout à fait s'en passer, même si il n'est pas gênant.

je n'en vois pas l'interet non plus. — YannUbuntu 2009/07/06 09:37

• config – fournit par défaut, permet de changer les paramètres de configuration avec une interface simple. Pareil que pour les ACL, ces paramètres doivent être gérée par du commit/push selon moi.
• infos – inclus, fournit des infos sur dokuwiki et les plugins installés
• note – Permet d'insérer des bulles d'infos.
• orphans wanted – Affiche des listes de pages manquantes ou qui ne sont référencées sur aucunes pages.
• page liste – affiche dans un tableau une liste de pages, utilisés par d'autres plugins.
• page move – déplace une page, corrige les liens sur les autres pages. Utilisable uniquement par les admins. Est-ce qu'ils l'utilisent vraiment?

on peut s'en passer grace aux backlinks. Mais ca peut etre pratique (si fiable). — YannUbuntu 2009/07/06 09:37

• pageredirect – applique une redirection vers une autre page sur une page existante.

indispensable. — YannUbuntu 2009/07/06 09:37

• plugin – inclus, gestion graphique des plugins
• popularity – inclus, permet d'envoyer des stats d'utilisation aux créateurs de dokuwiki, a ne pas utiliser sauf éventuellement si ils nous le demandent.
• revert – inclus, recherche et corrections de plusieurs pages dans le cas de spams.
• tag (déjà utilisé) gestion de tags

comme les tags sont tres majoritairement des pages existantes, et que les listes "pages contenant le tag xx" ne sont pas fiables, je me demande si on ne pourrait pas se passer du plugin… — YannUbuntu 2009/07/06 09:37

• usermanager – inclus, gestion des utilisateurs, non utilisé vu qu'on se sert de punbb pour ça

Il faut ajouter quelques plugins à notre cher dokuwiki pour améliorer l'apparence des pages. C'est une volonté récurrente sur la liste, et cela rentrerai également dans le cadre du nouveau design. En vrac quelques plugins à tester.

• addnewpage permet d'ajouter sur une page un mini formulaire d'aide à l'ajout d'une nouvelle page. On rempli le formulaire, on choisit le namespace dans un menu déroulant, et en appuie sur créer (exemple http://doc.yoboy.fr/wiki/ajouter ) On peux filtrer les namespace non désirés dans la configuration, ou n'afficher qu'un namespace. On ne peut avoir qu'un formulaire par page par contre. Pas super intéressant au final, et trop simple à mon avis, donc inutile.
• bookmarkme – liens vers les "marques pages sociaux". Je trouve que c'est intéressant de pouvoir marquer simplement une page sur notre "répertoire" de marques pages préférées. Donc je suis pour. Faudrait voir si ça ne perturbe pas les performances globales.
• force preview forcer l'aperçu en grisant le bouton enregistrer tant qu'on a pas au moins fait un aperçu. Simple, efficace, et suffisant selon moi.

pour. — YannUbuntu 2009/07/06 09:37

• htmlOKay permet l'utilisation d'html dans les pages du wiki désirée. Pas super simple à utiliser, pas mis à jour depuis 2007, possibilité de failles de sécurité… on oubli.
• include – inclus une page ou une section dans une autre. Semble intéressant à première vue, mais plus comme une base d'étude pour la création de plugins persos…
• on denied login – Lorsqu'un utilisateur tente d'accéder à une action dont-il n'a pas le privilège, il est renvoyé sur la page de connexion. Si on durcie les ACL, ce serait un bon moyen de rappeler à l'utilisateur de se connecter.

Si on ajoute un bouton "Participer au wiki" dans le menu de gauche, on devrait pouvoir s'en passer. — YannUbuntu 2009/07/06 09:37

• tag entry choisir les tags en cochant des cases.
  Ne convient que pour un wiki avec peu de tags. Il nous faudrait en fait une autre façon de faire.
• snippets inclusion directement dans l'éditeur de pages ou de morceaux de pages, idéal pour les "modèles" éventuellement. Pas réussi à le faire marcher.

• pagetemplate à étudier, mais ça à l'air bancal
• OpenID idem
• boxes après un rapide coup d'oeil ça à l'ai super bancal
• …

Base pour une refonte éventuelle de la page Thesaurus

Appliquer un tag c'est se demander : "Y a-t-il besoin d'une page regroupant des liens vers toutes les pages concernant ce sujet?"

Question 1: À partir de combien de pages est-il nécessaire d'avoir un tag pour gérer ce groupe de pages?

une petite dizaine? — YannUbuntu 2009/07/06 09:37

Question 2: Que penseriez-vous de mettre les tags sur deux lignes, la première contenant les tags propres au contenu de la page, la deuxième contenant exclusivement les tags des versions concernés, comme par exemple:
Dapper Feisty Gutsy Hardy
matériel réseau wifi

bof. pas esthetique et fait perdre de la place. — YannUbuntu 2009/07/06 09:37

Anciennes versions qui ne sont plus supportées
Les pages et informations concernant ces versions sont amenées à disparaître, ainsi que ces tags.

• Warty – Ubuntu 4.10 Warty Warthog
• Hoary – Ubuntu 5.04 Hoary Hedgehog
• Breezy – Ubuntu 5.10 Breezy Badger
• Edgy – Ubuntu 6.10 Edgy Eft
• Feisty – Ubuntu 7.04 Feisty Fawn – (synonymes: 7.04)
• Gutsy – Ubuntu 7.10 Gutsy Gibbon – (synonymes: 7.10)

Versions supportées
Les pages doivent être écrite dans l'optique d'aider l'utilisateur sur toutes ces versions, et en particulier les versions LTS. Mettre les tags pour lequel les informations sur la page conviennent.

• Dapper – Ubuntu 6.06 LTS Dapper Drake – (synonymes: 6.06 6.06_lts)
• Hardy – Ubuntu 8.04 LTS Hardy Heron – (synonymes: 8.04 8.04_LTS)
• Intrepid – Ubuntu 8.10 Intrepid Ibex – (synonymes: 8.10)
• Jaunty – Ubuntu 9.04 Jaunty Jackalope – (synonymes: 9.04)

Versions en cours de développement Ces tags apparaissent à partir de la sortie de la première bêta (évitez d'écrire des informations sur des versions alpha qui peuvent ne plus être adéquates avec la version finale).

• Karmic – Ubuntu 9.10 Karmic Koala (à paraître) – (synonymes: 9.10)

Tout matériel, périphérique externe, carte interne, chipset, ordinateur complet, … dont l'utilisation nécessite la création d'une page doit se voir attribué le mot-clé matériel (notez l'accent) suivi d'un ou plusieurs tags décrivant le type de matériel.

• portable (pour les fixes, ne mettez que la marque)
  • Le type (facultatif) – netpc (eee et les autres) tabletpc
  • La marque (facultatif) – Acer Alienware Aopen Airis Apple Asus Averatec Clevo Compal Compaq Dell Fujitsu_Siemens Gateway Gericom Hewlett_Packard IBM I-Note Keynux Lenovo Materiel.net MaxData Medion MSI Nec Packard_Bell Panasonic Samsung Sony Targa Toshiba Uniwill Zepto
  • Le modèle (facultatif dépendant de la marque, peu utilisé)
• carte_graphique
  • ATI – (synonymes: AMD-ATI)
  • nVidia
  • Intel
  • Les autres marques – Matrox Via 3DFx ne sont pas signalés en mots clés
  • Fonctions complémentaires – aquisition_video carte_tv(regroupe aussi les cartes TNT)
• disque_dur – Les différents disques durs, externes généralement
  • Type de connection – usb firewire réseau
  • raid
  • multimédia
• réseau – Tout ce qui touche au réseau
  • wifi
  • modem
  • routeur
• carte_son – Les cartes sons
• Les supports de stockage
  • disquette
  • zip
  • cd
  • dvd
  • bd
  • carte_mémoire
• graveur – Les graveurs
  • cd
  • dvd
  • bd
  • usb
  • scsi
• Les périphériques
  • souris
  • clavier
  • télécommande
  • tablette
  • webcam
• imprimante – Les imprimantes de toute sorte
  • réseau
  • wifi
  • multifonctions
  • cartes_mémoire
• scanner – Les scanners (hors imprimantes)
• Les ports d'entrée/sortie
  • usb
  • firewire
  • PCMCIA
  • irda
  • bluetooth
  • scsi
  • série
  • parallèle
• Les autres types de matériel
  • mobile
  • appareil_photo
  • caméra
  • clé_usb
  • sécurité
  • énergie

Ces tags permettent de catégoriser les logiciels, une bonne pratique est de voir comment sont taggés les logiciels similaire. Une autre bonne pratiques est de regarder où apparaît le raccourcis dans votre menu Applications, car celui ci est déjà dans une catégorie. En premiers tags on peux préciser à quel environnement de bureau le logiciel est destiné si tel est le cas ou quelle configuration il utilise.

• Gnome KDE XFce
• GTK QT Motif Java Console

Ensuite vient la catégorisation suivant le type de logiciel, une bonne pratique serait de suivre les catégories déjà définies par freedesktop.org

• Audio
  • Média-thèque Radio Lecteur Musique
  • MIDI Mixer MAO Acquisition
  • Gravure
• Vidéo
  • Média-thèque TV Lecteur Montage Acquisition
  • Gravure
• Programmation
  • Debug IDE GUIDesigner Compilation Traduction Versioning bdd Gestion_Projet
• Éducation
  • Art Construction Musique Langue Science IA Astronomie Biologie Chimie Informatique Économie Électricité Géographie Géologie Histoire Imagerie Littérature Math Médecine Physique Robotique Sport
• Jeux
  • Action Aventure Arcade Plateau Casse_Brique Cartes Enfant Logique JDR Simulation Sport Stratégie Émulateur
• Graphisme
  • Dessin Vectoriel 3D PAO Photo
  • Acquisition OCR Visionneuse
• Internet
  • courrier messagerie Chat IRC Newsgroup Vidéo_Conférence
  • Téléchargement P2P Navigateur
  • Communication Radio Accès_Distant Téléphonie
• Bureautique
  • Agenda Carnet_Adresses bdd dictionnaire courrier visionneuse
  • Présentation Tableur Traitement_Texte PAO
  • Comptabilité Gestion_Projet
  • PDA
  • Électronique Électricité CAD
• Accessoires
  • Éditeur Sauvegarde Compression Navigateur_Fichier Accessibilité Calculatrice Horloge
• Système
  • Emulateur Terminal Gestionnaire_Fichier Moniteur Sécurité Gestionnaire_de_paquets
• Configuration
  • imprimante webcam scanner carte_graphique carte_son …
  • Bureau Fond_Écran Icônes Son
  • Sécurité Accessibilité

En premier lieu un tutoriel doit comporter le tag tutoriel.

Toutes les pages sont en quelque sorte des tutoriels, néanmoins on considère une page comme un tutoriel lorsque celle-ci fait appel à des notions et des procédures faisant généralement intervenir plusieurs applications.
Par exemple une page expliquant comment lire une vidéo en présentant les codecs et les divers programmes possibles est un tutoriel, alors qu'une page présentant totem le lecteur vidéo de gnome uniquement n'en est pas un.

En plus du tag tutoriel ces pages comportent les tags correspondant à ce qu'elles expliquent choisis dans les tags matériels et/ou les tags d'applications.

1- Une imprimante multifonction avec lecteur de carte testé sous Dapper Gutsy Hardy:

Dapper, Gutsy, Hardy
matériel, imprimante, multifonctions, carte_mémoire

2- Aptitude:

Dapper, Edgy, Feisty, Gutsy, Hardy
Console, Système, Gestionnaire_de_paquets

3- Totem:

Dapper, Edgy, Feisty, Gutsy, Hardy
Gnome], GTK, Audio, Vidéo, Lecteur

4- Tutoriel sur Comment accéder à ses partitions windows:

Dapper, Edgy, Feisty, Gutsy, Hardy
windows, Disque_Dur, Réseau, Navigateur de fichier

Le nuage de tags recense beaucoup de tags qui sont des erreurs ou qui ne devraient pas être utilisés