asso:tuto:wiki

Utilisation et contribuer au Wiki

Le wiki de Picasoft vise à recenser un ensemble de pages sur plusieurs thèmes, comme par exemple :

  • Le fonctionnement de l’association,
  • L’infrastructure technique,
  • Les bilans moraux et financiers,
  • Les rapports des TX co-encadrée par Picasoft,
  • Des tutoriels sur différentes technologies…

L’outil le plus important du Wiki est sans doute la fonction recherche, qui vous permettra de trouver rapidement les pages parlant du sujet qui vous intéresse.

Il est organisé hiérarchiquement par catégories. L’index que vous voyez à gauche de cette page est généré automatiquement à partir de cette hiérarchie. Différents icônes permettent de vous déplacer plus facilement dans l’arborescence :

  • Les catégories sont indiquées par l’icône
  • Les pages sont indiquées par l’icône

Enfin, si au survol d’une catégorie avec la souris, vous voyez apparaître un petit triangle rouge, cela signifie que la catégorie a un index et que vous pouvez cliquer dessus. Dans le cas des catégories sans index, un clic se contentera de dérouler l’arborescence.

Les catégories peuvent aussi se voir dans l’URL de la page, dont le format est le suivant : ?id=catégorie:sous-catégorie:...:nom. Comme vous pouvez le voir sur cette page, le nom est wiki, la catégorie est asso et la sous-catégorie est tuto.

Pour faire référence à une page interne au wiki, on utilisera les références internes de Dokuwiki, via le bouton

En effet, ces références seront automatiquement mises à jour si les pages sont déplacées avec le plugin move de Dokuwiki, ce qui permet d’éviter les liens morts.

Pour les images, on préférera utiliser le Gestionnaire Multimédia et l’insertion d’image via le bouton

En effet, on ne peut pas garantir que des images provenant d’un site extérieur persistent, tandis qu’en les téléversant sur le wiki, elles sont pérennes.

On préférera la syntaxe Markdown pour la facilité d’édition.

Note:

Le plugin bootnote permet de créer des cadres attirant l’attention sur une information.

Pour éditer une page, il vous faudra un compte. Vous pouvez demander à n’importe quel membre de l’association d’activer votre compte, après quoi vous pourrez l’éditer en cliquant sur l’icône présente dans le menu à droite de la page.

La mise en forme du texte peut se faire à l’aide de la syntaxe Markdown ou de la syntaxe Dokuwiki, la première étant plus simple à prendre en main.

Le bouton en forme d’horloge permet de visualiser les anciennes versions de la page, vous permettant de revenir sur une erreur, par exemple.

Dans la barre de menu, en haut, l’icône en forme de document vide vous permettra de créer une nouvelle page. Il vous faudra choisir la catégorie appropriée. Les catégories existantes à ce jour devraient suffire pour la plupart des cas.

Il est possible de créer une page directement en modifiant l’URL d’une page existante. Par exemple, pour créer cette page, je me suis simplement rendu sur l’URL https://wiki.picasoft.net/doku.php?id=asso:tuto:wiki et j’ai cliqué sur le bouton de modification de la page.

Il est important de donner un titre à la page, car c’est lui qui apparaîtra dans l’index auto-généré. En Markdown, on l’indiquera en le précédant d’un caractère # au tout début de la page.

Dans le cas où les catégories existantes ne suffisent pas, par exemple pour une nouvelle TX, on pourra en créer une nouvelle. Pour ce faire, il suffit de créer une page “comme si la catégorie existait”, et la nouvelle catégorie sera automatiquement ajoutée dans l’arborescence.

Vous remarquerez que par défaut, les catégories n’ont pas de nom “lisible par l’homme”, mais que leur identifiant s’affiche. Pour des raisons de lisibilité, si on veut y attribuer un nom arbitraire, il faudra créer une page start dans la catégorie nouvellement créée, et lui assigner un titre (avec # en Markdown).

La catégorie deviendra alors cliquable dans l’arborescence et amènera sur la page start, qui ne contient que le titre. Il est alors de bon ton d’y ajouter un index auto-généré, ce qui peut être fait avec cette syntaxe (remplacez categorie et sous-categorie par les bons noms) :

{{indexmenu>:categorie:sous-categorie:...|js#bitrix msort tsort msort nsort notoc nomenu nocookie navbar}}

Pour rendre les concepts un peu moins abstraits, prenons le cas le plus compliqué : je veux créer une nouvelle catégorie pour une TX sécu se déroulant au printemps 2020, pour y ajouter des pages sur le travail effectué.

Je commence par créer une page d’index : je me rends sur https://wiki.picasoft.net/doku.php?id=txs:secu:p20:start et j’ajoute ce contenu :

# Audit de sécurité de l'infrastructure de Picasoft

{{indexmenu>:txs:secu:p20|js#bitrix msort tsort msort nsort notoc nomenu nocookie navbar}}

La page d’index est créée, référencée dans la barre latérale et les nouvelles pages de cette catégorie seront auto-indexées.

Par exemple, je crée deux nouvelles pages. La première, txs:secu:p20:etude, avec pour contenu # Étude de l'infrastructure existante, et la seconde, txs:secu:p20:recommandations, avec pour contenu # Recommandations suite à l'audit.

Le résultat sera immédiatement le suivant :

Comme vous pouvez le voir, la nouvelle catégorie et l’ensemble des pages créées sous cette catégorie sont correctement et automatiquement référencées.

Par défaut, Dokuwiki trie les pages dans la barre de navigation (à gauche ou avec un sommaire autogénéré par la balise {{indexmenu}}) par ordre alphabétique du titre, ou à défaut de l’identifiant de la page.

Parfois, on voudrait choisir l’ordre au sein d’une catégorie pour montrer une progression logique, par exemple :

Administrer le serveur mail

  1. Vérifier les journaux
  2. Changer un paramètre
  3. Modifier le mode de connexion LDAP

Une première solution serait de créer un sommaire à la main, mais celui-ci est figé et n’évolue pas lors de l’ajout d’une nouvelle page, ce qui le rend inutile.

C’est la solution la plus évidente, assez peu élégante mais fonctionnelle.

Dokuwiki peut trier les pages en fonction de métadonnées, avant de passer à l’ordre alphabétique des titres. La solution la plus simple pour utiliser ce type de tri est d’ajouter au début de chaque page le code suivant :

{{indexmenu_n>N}}

N est un nombre entier qui servira à spécifier l’ordre de tri.

Une bonne pratique est d’utiliser des dizaines dans un premier temps : 1 pour la première page, 10 pour la deuxième, 20 pour la troisième, etc. De cette manière, l’insertion d’une page entre la première et la deuxième pourra se faire avec N = 2, sans avoir à tout décaler.

Cette solution est préférée car automatique et sans besoin d’intervention manuelle quand une nouvelle page est intercalée.

  • asso/tuto/wiki.txt
  • de qduchemi