Outils pour utilisateurs

Outils du site


procedure_doc_wiki
Contributeurs Luc Brucher, Frantz de Germain
Mots clefs
Statut

Organisation doc wiki "DDN"

Pourquoi un Wiki ?

Un wiki permet, par exemple, de mettre en commun toute une documentation, de façon collaborative 1). La mise en page est prise en charge par le Wiki. Associée à nos types de documents, cela permet d'avoir un rendu uniforme, agréable et structuré. L'édition des pages reste donc plutôt aisée 2). Ce wiki est destiné à mettre à disposition de l'ensemble de la DDN des informations internes de différents types.

Le wiki DDN

Chacun est invité à l'alimenter avec les informations dont il dispose, soit en créant des pages, soit en intervenant sur des pages existantes, même s'il n'en est pas l'auteur. Le contributeur indiqué en haut des pages est le créateur initial de la page. Il peut y avoir plusieurs contributeurs. Dès lors que vous avez fait des modifications importantes sur une page, ajoutez votre nom à la liste. Par ailleurs l'ensemble des contributions à une page est accessible via la notion de révisions.

Le retour en arrière à une ancienne révision est simple, il ne faut donc pas hésiter à intervenir sur une page.

Les administrateurs du Wiki (actuellement Frantz de Germain et Luc Brucher) sont chargés de veiller à la bonne application des règles d'usage.

Les informations contenues dans les pages DDN sont à usage interne DDN.

Plan de la formation wiki pour la DDN de mars 2014
8, 10 et 12 personnes présentes aux 3 sessions.
  1. Présentation rapide du wiki et des règles de base. Rôle des administrateurs du wiki. Discussions autour du wiki.
  2. Détail des règles d'organisation du wiki
    • Les types de documents
    • Le nommage des pages
    • Les mots clefs
  3. 1ère manipulation : création d'une page de type “HOWTO” : détails dans Utilisation du Wiki (connexion, toc, FAQ, plugins,…)
    • L'éditeur
    • Les syntaxes principales (:!: désormais francisée :-) )
    • L'enregistrement
    • L'édition par bloc (+ champ “Résumé”)
    • La notion de révision exemple
    • Joindre un fichier
    • Déplacer/renommer une page
  4. 2ème manipulation : recherche de documents, les différentes logiques d'accès ; se tenir au courant : voir “Recherche de documents” plus bas.


Règles de base

  • Toute documentation est créée au format Wiki sauf quand celui-ci n'est pas adapté (plans, schémas…).
  • Les documents qui sont créés avec un autre outil sont stockées sur le partage DDN-SSR au format source de l'application utilisée. Ils sont également exportés dans un format lisible sans outil spécifique (Image, PDF…). Ce fichier est alors uploadé sur le wiki pour publication. Il est systématiquement référencé dans un document wiki.
  • L'espace de nom “ddn” est subdivisé en types de documents plutôt que par thème. Les types de documents sont référencés plus bas.
  • Chaque type de document est associé à un modèle, c'est à dire une trame de remplissage imposée. Cette trame peut-être plus ou moins précise selon le type de document. Dans les modèles, les section entre “<” et ">" sont à remplacer par la valeur adaptée. Les textes en italiques sont des indications sur la façon de remplir le document, ils sont à supprimer quand le document est rempli.
  • Le nom des documents fait apparaître les termes qui permettront de le retrouver rapidement en accès “recherche” (les pages contenant les termes recherchés dans leur nom apparaissent s'affichent “à la volée” lors d'une recherche et/ou en tête des résultats de recherche). On n'utilise que des mots en minuscules et au singulier, séparés par des “_” (souligné), pas d'articles. Le début du nom des documents d'un type donné est toujours le même de façon à faciliter l'identification de celui-ci, notamment dans les résultats de recherche. Par exemple pour le type fiche_serveur, tous les documents commencent par “serveur_” suivi du nom du serveur.
  • Des mots-clefs peuvent être associés à chaque document (à saisir dans le cartouche en haut à gauche présent dans tous les modèles) pour faciliter encore la recherche. Ils sont répertoriés automatiquement dans la page d'accueil ddn sous forme d'un "nuage" de mots-clefs. Les mots-clefs respectent les mêmes règles que les mots composant le nom du document (minuscules, singulier). Le séparateur de mots-clefs est l'espace, un mot-clef composé de plusieurs mots est mis entre guillemets.
  • Le wiki n'est pas un outil de traitement de texte, il ne faut pas chercher à obtenir une “belle” mise en forme mais se concentrer sur le contenu structuré à travers la notion de titres et de listes notamment. La mise en forme est imposée par l'outil à l'ensemble des pages ce qui assure une homogénéité à l'ensemble, les modèles amène un niveau supplémentaire d'homogénéité.
  • Les documents obsolètes sont signalés par la mention “obsolète” sous forme de warning dans le champ état du cartouche (en haut à gauche).

Aucun mot de passe ne doit apparaître en clair dans les documents publiés sur le wiki. Ceux-ci sont stockés par ailleurs de façon encryptée.

Types de documents

Les types de documents actuellement prévus sont (en ordre alphabétique) :

  • contrat : document décrivant un contrat/marché/convention…
  • cr_reunion : compte rendu de réunion (ou relevé de décision). On convient de nommer les documents de ce type ainsi : cr_aaaammjj_partie_libre. Afin d'avoir un affichage chronologique.
  • fiche_action : document décrivant une action à mener et son avancement. Il peut s'agir d'un sous-projet d'un projet plus vaste de la DDN.
  • fiche_instance : document décrivant une instance de base de donnée (Oracle pour le moment)
  • fiche_projet : fiche de suivi de projet. Il s'agit de décrire et de suivre quelque chose de plus vaste qu'une simple action. Un projet est associé à un pilote, voire un comité de pilotage, dispose d'un budget, est en général validé par la CPN…
  • La documentation d'une application (au sens large), s'appuie sur 3 catégories de fiches :
    • fiche_application : fiche descriptive de l'application . Cette fiche contient des données suffisantes pour identifier le périmètre fonctionnel de l'application , quels acteurs (éditeurs,mainteneur…) , conditions d'accès.
    • fiche_infra_appli : fiche décrivant l'infrastructure technique d'une application (serveurs impliqués (synoptique), mode d'installation, logiciels de base, présenter les modèles, les choix, lister les principaux fichiers de conf…)
    • fiche_pclient_appli : ficher décrivant les prérequis du poste client pour l'accès à une application.
  • fiche_serveur : description d'un serveur. Noms des documents structuré ainsi : “serveur_nom_du_serveur
  • fiche_service : description d'un service (exemple mise en place d'un client Bacula ou Tina…). Noms des documents structuré ainsi : “service_nom_du_service OBSOLETE, voir les catégories: fiche_application, fiche_infra_appli et fiche_pclient_appli.
  • howto : description d'un mode opératoire technique lié au contexte local adopté par la DDN. Éviter les copies écran ; utiliser le > pour indiquer l'accès à des sous-menus
  • incident : document décrivant un incident c'est à dire un problème ayant entraîné un dysfonctionnement important des services fournis (exemple: incident électrique ayant eu des répercussions importantes sur les services rendus) ou un problème de sécurité (exemple piratage d'un serveur…)
  • inventaire : document de type tableau listant des “objets” (exemple inventaire des baies, inventaire des serveurs, inventaire des actions en cours…). Noms des documents structurés ainsi : “inventaire_partie_libre)
  • journal : document de type tableau listant des actions ou des évènements sur un sujet donné en ordre chronologique inverse
  • memento : toute information, pense-bête, commandes utiles, trucs et astuces qu'il semble utile de partager.
  • procedure : tout document décrivant une façon de procéder d'un point de vue organisationnel… (exemple : de document décrivant la façon de gérer la documentation au sein du wiki). Les modes opératoires techniques adoptés par la DDN sont à classer en “howto”. Les autres modes opératoires sont à classer en “memento”.
  • sommaire : document de navigation par thème. Il référence d'autres documents de façon organisée par thème. Noms des documents structuré ainsi : “sommaire_partie_libre
  • synoptique : document décrivant l'organisation de principe d'un service (exemple : le service ldap, le service mail…). Peut être sous forme de textes et/ou de schémas.

Arborescence du wiki

Voir plan du site, en haut à droite des pages.

NB : l'espace de nom dsi: est obsolète, et à nettoyer/déplacer.


Les modèles sont présents dans chaque espace de nom et sont nommés *_modele (exemple serveur_modele). Un lien symbolique est fait par les administrateurs du wiki pour que le document soit bien considéré comme “template” par dokuwiki.

Etats d'un document

Le champ “Etat” (anciennement “Statut”) du cartouche de chaque document permet de donner une indication complémentaire sur la valeur des informations qu'il contient et son positionnement dans le cycle de vie d'un document. Afin d'homogénéiser la façon de remplir ce champ, on recense ci-dessous les valeurs possibles.

  • Valeurs génériques
    • obsolète : Les informations contenues dans le document ne sont plus à jour. On peut préciser si le document est à garder à titre d'historique, ou s'il est nécessaire de le réécrire pour le mettre à jour
    • en cours de rédaction : le document est incomplet mais il va être complété rapidement (brouillon, ébauche). A n'utiliser que si la rédaction est effectivement en cours pas pour indiquer que le document est à compléter
  • Valeurs spécifiques au type “cr_reunion” :
    • proposition ODJ : La réunion n'a pas encore eu lieu, il s'agit donc d'une proposition d'ordre du jour. Aucune partie autre que l'ordre du jour ne doit être remplie avant la réunion
    • non validé : Le compte rendu n'a pas encore été validé par l'ensemble des participants
    • validé le <date> : Le compte rendu a été validé par l'ensemble des participants. Aucune modification ne doit être apportée après cette date (sauf correction de fautes d'orthographe ?)
  • Valeurs spécifiques aux types “action” et “projet”
    • en cours : L'action est en cours
    • terminé : L'action est terminée, conservée pour historique

Recherche de documents

  • Par le nom de la page (Affichage “à la volée” 3) des noms de pages ⇨ d'où l'intérêt de bien respecter les règles de nommage)
  • Par recherche sur le contenu 4) :
    • la recherche d'un mot contenant le caractère “_” ou ”-“ doit se faire en l'entourant de guillemets, sinon, il sera considéré comme un espace
    • seule la chaîne exacte est recherchée. On peut utiliser le caractère ”*“
  • Par l'index général : ”plan du site en haut à droite des pages
  • Depuis les mots-clefs, dans les cartouches en haut des pages, ou le nuage de mot-clefs (Voir ci-dessous)
  • Par les pages sommaire_xxx (Voir ci-dessus)
  • En suivant des liens (⇨ pensez aux liens internes vers d'autres pages de notre Wiki, cf. section “Voir aussi” en bas des pages)
  • En suivant la “Piste” en haut des pages : historique des pages que vous avez visitées lors de votre session
  • Derniers changements :
    • ici ou lien “derniers changements” 5) en haut des pages, ou ajouter ?do=recent à la fin de l'URL 6)
  • S'abonner aux pages7), espaces de noms 8) 9) et même mots-clefs 10) : cliquer sur l'enveloppe dans la boîte à outil flottante

Mots-clefs

Permet deux types de recherche thématique :

Règles

  • Toujours au singulier et en minuscules
  • Pas d'article
  • 2 ou 3 mots clés maximum par page, et de sens vraiment différents
  • Vérifier avant de mettre un mot-clef, qu'un équivalent n'est pas déjà présent dans le nuage
  • Destinés à une recherche thématique ⇨ le mot clé doit avoir une portée générale (pas trop spécifique 11) : ex.: noms propres)
  • Doit concerner potentiellement plus de 2 ou 3 pages, mais pas trop (50 ? ex.: windows)
  • Peut être déclaré dans une page dont le nom comporte le mot clé

Règles particulières par type de document

fiche_serveur

  • Les champs minimum à remplir pour la création d'une fiche serveur sont ceux du tableau en début de page. Les autres informations peuvent être complétées par la suite en fonction de leur importance.

Merci de soumettre toutes remarques, propositions sur la gestion de la doc dans le wiki via le “forum de discussion” en bas de cette page.

Points à aborder lors d'une prochaine réunion Wiki

Partie réservée aux administrateurs du wiki pour noter au fil de l'eau les points à caler dans l'usage du wiki au vu du suivi des fiches créées.

  • Choix de l'ordre des mots dans le nom d'une page : commencer par les mots les plus discriminants (exemple : howto_zimbra_admin plutôt que howto_admin_zimbra)
  • Calage des rubriques de l'entête : il est important que celles-ci soient bien définies et remplies avec la même nature d'information. Notamment :
    • “type” dans les fiches serveur : doit se limiter à la liste des valeurs proposées dans le modèle
    • “porteur” dans les fiches projet : doit être le nom d'une personne.
    • Rubrique “Etat” : spécifique aux CR ou à généraliser pour tous les documents avec éventuellement des valeurs spécifiques pour certains types comme les CR.
  • Revoir structuration fiche serveur (concerne surtout SSR)
  • Modèle de la fiche_action : ajout d'une partie “synthèse” ?
  • Importance de noter sur chaque document son statut : s'agit-il d'un document en cours d'élaboration ou d'un document validé notamment
  • Ne pas laisser les textes guides des modèles lorsque l'on crée une page, cela brouille la lecture.
  • Rebalayer les types et leur usage
  • Revoir la notion de mot-clef : proposition d'aller plutôt vers une notion de “thème” (exemple “controle acces” pour marquer toutes pages liées au système de contrôle d'accès de l'UA)
    Imposer le référencement des mots clefs avec une définition ?
  • Revoir les plugins (faut-il tout garder). Notamment question sur : “encrypted passwords”
  • Utilisation des italiques : réserver à des aides à la rédaction liées au type de page. Ces aides sont présentes dans le modèle. Elles sont destinées à être supprimées dans les documents, une fois que les parties concernées ont été remplies.
  • Proposition : mettre systématiquement le nom du type de document en tête du “cartouche”
  • Proposition : dans les parties listant des évènements chronologiques : utiliser toujours une chronologie inverse (plus récent en premier).
  • (LuB) Proposition : Ajout d'un champ dans le cartouche des CR de réunion pour mettre les initiales des personnes ayant validé le CR (facilite la validation globale du CR).

Voir aussi

1)
N'hésitez pas à corriger les éventuelles fautes d'orthographes ou erreurs d'utilisation des balises de syntaxe.
2)
Syntaxe relativement simple avec barre de boutons en haut de la fenêtre d'édition
3)
.i.e avant de taper Entrée dans le champ de recherche
4)
.i.e après avoir tapé Entrée dans le champ de recherche
5)
de l'espace de noms courant
7)
particulièrement, les vôtres et les pages sommaire_xxx
8)
particulièrement, cr_reunion:
9)
dans ce cas, vous pouvez opter pour une “liste des pages modifiées depuis le dernier envoi” (1/jour max)
10)
depuis la page listant les pages d'un mot-clef
11)
les mots plus spécifiques pourront être retrouvés grâce à la recherche par contenu

Propositions, remarques

Entrer votre commentaire. La syntaxe wiki est autorisée:
 
procedure_doc_wiki.txt · Dernière modification: 2018/10/03 16:17 par De Germain Frantz