Capitalisation des connaissances

Sous cette locution à la mode se cache un problème qu'on peut qualifier de NP-complet[2].

En effet, comment extraire la connaissance de nos têtes de façon à la reverser dans la tête des autres ? De même, comment faire lorsque un employé démissionne pour que ce ne soit pas un pan entier de compétences qui parte avec lui ? Ce problème est encore plus criant pour les petites sociétés. Enfin, si on se place du point de vue de la SSII/SSLL qui reçoit des demandes de compétences spécifiques, comment identifier les intervenants qui siéront au client ?

Lorsque je suis arrivé en 2002 dans l'équipe qui se montait pour assurer l'externalisation, je ne devais rester que quelques semaines. Ce devait être histoire de mettre la production sur les rails avant de repartir sur mes missions ponctuelles comme auparavant. Je suis donc arrivé pour préparer mon départ. Dans mes précédentes missions en régie, j'avais déjà monté des serveurs Web pour en faire le lieu central où seraient déposées les documentations internes, mais rien de très facile sur lequel publier.

Pourquoi le Web ? Parce que cela ne nécessite qu'un client léger (enfin, plus léger qu'un OpenOffice ou MS-Office), que la mise en forme est relativement simple et surtout qu'on a toujours un navigateur à disposition. Même quand on est sur une machine Unix sans carte graphique. Et il est toujours plus agréable de lire de la doc avec links ou lynx qu'avec un strings toto.doc | less...

Même si l'on suit les recommandations d'IBM (H1, P, UL/LI, TT/PRE et c'est tout), l'inconvénient du HTML est qu'il faut quand même un logiciel un peu évolué pour écrire la documentation (message personnel : j'ai perdu l'URL où cette recommandation d'IBM était présentée).

Demander à un néophyte en HTML (cela existe, même chez les informaticiens) d'écrire de la documentation en se souciant de refermer les tags écrits à la main dans un notepad ou dans vi est un bon moyen de le dégoûter. À l'inverse, en utilisant un logiciel plus évolué tel qu'un traitement de texte, les utilisateurs vont passer plus de temps à ce soucier du corps de police que du contenu. Je passe sur LaTeX et autre DocBook qui ne sont pas adaptés à ce type de documentation qui doit pouvoir être écrite rapidement.

Le mode texte pur, c'est pas mal, mais imprimer tout ça en police Courier n'est pas super lisible non plus. De plus, on ne peut pas insérer d'image ou de schéma facilement à moins d'avoir l'aalib sous la main ou d'être un dieu en ASCII-art. Nous le laisserons donc aux seuls rédacteurs de RFC.

Un dernier inconvénient de ces différents formats est qu'il faut des outils spécifiques pour y effectuer des recherches. L'installation de ht:/dig est simple, mais il n'indexe que du HTML ou du texte. Il nécessite donc l'installation d'outils supplémentaires comme catdoc et xlscat pour convertir les formats MS Word et MS Excel, pdftotext (livré avec xpdf) pour le PDF, unzip plus un outil d'extraction XML pour le format OpenOffice ou OpenDocument. Et cela pour les formats que l'on sait convertir, ou pire : quand les outils fonctionnent !

L'idéal serait donc d'avoir un outil qui autorise en standard :

une édition facile (pas d'usine à gaz) et rapide de documents,
l'indexation de ces documents,
une présentation de type web pour que tous en profitent facilement,
une gestion minimum des droits de publication.

Si en plus il permet de modifier la charte graphique du site sans toucher au contenu, de générer des fichiers PDF, gère des mots-clés, et permet aux auteurs des documents de se faire un peu de pub en interne, c'est tout bénéfice.

Ça n'existe pas, ça ?

L'écureuil libre

Bah si. Ça s'appelle SPIP[3] (Système de Publication Pour l'Internet), c'est un projet français et ça sert au départ à gérer un journal en ligne. Plusieurs journaux l'utilisent, dont le Monde Diplomatique, quelques sociétés tant pour leurs sites web ou d'autres besoins, des sites militants, des partis politiques, des formations syndicales, des télévisions (France Télévisions) et même plusieurs ministères sous sa forme Agora. Le but de SPIP était au départ de fournir un outil de publication accessible au débutant ou au réfractaire à l'informatique. SPIP a été développé en PHP et utilise MySQL. On peut donc l'installer partout ou presque (mes collègues ont dupliqué notre base de connaissance sur leur portable grâce à EasyPHP).

Nous avions regardé (rapidement) quelques autres outils comme les P*Nuke qui semblaient plus adaptés à la construction d'un site de news qu'à une base de connaissance. Les wikis aussi, mais la forme, tout comme les P*Nuke était limitée, voire moche. Car c'est tout de même sympa de bosser avec un outil sexy. Puis je suis tombé sur un mél de l'excellent Pierre B. Jarret de l'Académie de Soissons qui conseillait l'utilisation de SPIP. Voilà comment nous en sommes arrivés là.

D'autres possibilités n'ont pas été explorées : les CMS à base de Java, comme OpenCMS (qui n'existait pas lors de notre besoin) et ceux en Python comme Zope/Plone (qui semblaient lourds voire un peu « overkill » lors de l'analyse de notre besoin).

Il est vrai que l'utilisation de SPIP a été détournée. Je lisais il y a plusieurs mois dans la liste de distribution qu'un des auteurs s'étonnait que SPIP soit considéré comme un outil de GED (Gestion Électronique de Document). C'est pourtant le cas, même si ce n'est pas complet. Cela ne le sera peut-être jamais, car ce n'est pas forcément le but du projet. Toutefois, la gestion de version sur le contenu des articles est arrivée avec la version 1.8. Cette fonctionnalité permet de se rapprocher (un peu) de la GED pour ce qui nous intéresse.

SPIP, sans pour autant vouloir refaire l'excellente et pléthorique documentation, peut être vu sous quatre angles différents :

du visiteur, i.e. la partie publique du site ;
du producteur (des auteurs d'articles), autrement dit la partie privée du site ;
du webmestre (qui gère seul la mise en page du site), j'ai nommé les squelettes.
d'un certain nombre de lecteurs choisis, une partie partie publique à accès restreint[3] pour les informations pas forcément sensibles, mais plus techniques sur un SPIP mixte référence technique et vitrine d'une équipe.

Et je ne compte pas les flux RSS disponibles et personnalisables.

La partie publique est celle que n'importe quel internaute utilisera pour la consultation du site. Cette partie est modulable au gré du webmestre en fonction de ce qu'il va mettre dans ses squelettes. Je ne m'étendrai pas plus sur ce sujet, vous savez tous utiliser un navigateur. ;-)

La partie privée de SPIP n'est pas son côté obscur, loin de là. Toute la gestion de SPIP se fait là. C'est un tour de force quant à la clarté de l'interface. On y gère les rubriques, les articles et brèves, les mots-clés regroupés en thèmes (et non, ce n'est pas d'une utilisation marginale, ainsi qu'il est dit dans la documentation), les auteurs, les pétitions, les fora (un forum, des fora), etc.

Dans l'équipe, SPIP est utilisé un peu à la manière d'un wiki. On se passe donc quasiment de la gestion de workflow, sauf si nous avons des invités. Tous les permanents sont donc administrateurs, pour deux raisons. La première est que SPIP, en bon outil de publication, ne permet pas à un auteur simple de revenir sur un article qui a été publié. La seconde est que nous avons besoin de nous auto-publier, en ce sens que nous préférons une publication partielle, quitte à revenir par la suite sur les documents, à un cycle de validation long. Cela participe de la dynamique de documentation. Et comme SPIP sait indexer les documents, il suffit de glisser un petit mot comme « FIXME » pour retrouver les articles à augmenter. De même, un groupe de mots-clés concernant la documentation pourra voir le mot-clé FIXME attribué aux articles.

Pour le contenu de la documentation, SPIP s'appuie sur quelques tags très simples. Vous les retrouverez dans la documentation sur [2]. Citons les plus courants :

on passe une ligne pour indiquer un nouveau paragraphe ;
{ texte }, pour mettre les italiques ;
{{ texte }}, pour le gras ;
{{{ texte }}}, pour les inter-titres d'un article ;
le tiret suivi d'une espace en début de ligne, pour faire une liste à puce ;
on peut suffixer le tiret avec de une à trois étoiles (astérisques) pour avoir des sous-niveaux de listes ;
on peut aussi suffixer le même tiret avec un dièse (#) pour obtenir une liste numérotée ;
pour les tableaux, il suffit d'entourer les cellules par des pipes (|), et de vérifier que toutes les lignes ont le même nombre de cellules, sinon SPIP créera un nouveau tableau ;
on peut inclure des images ou des documents en les ayant téléchargés au préalable dans l'interface d'administration et en les référençant ensuite ainsi : <img234> ;
les liens hypertextes peuvent se faire très facilement dans le site ([texte->art123]) ou vers des URL (texte). Si texte est omis, le titre de l'article ou l'URL sera la partie affichée du lien. On peut aussi référencer des articles, des rubriques, des mots-clés, etc.

Comment construire sa base de connaissances

Le plus simplement du monde, en commençant par commencer.

Cette litote a l'air bête, mais il n'y a pas d'autre façon. SPIP permettant de séparer le contenu de la présentation (j'allais dire la forme du fond, mais ça n'est pas DocBook, quand même), on peut commencer très rapidement.

Il suffit pour ça d'installer SPIP (c'est d'une facilité déconcertante, pour peu que vous ayez un serveur Linux avec PHP et MySQL d'installés), de créer une première rubrique, d'y mettre un premier article, de le publier et c'est fini. Les squelettes seront pour plus tard : on s'intéresse au contenu, pas à la forme.

Sachez cependant que nous avons réalisé nos squelettes et qu'ils ont été faits sur le long cours, en fonction des besoins. Comme nous venions d'être rachetés, la charte graphique a changé. Ils seront sûrement refaits un jour, peut-être. Mais cela ne changera rien au contenu. Gardez seulement à l'esprit que le but du jeu est de faciliter l'accès à l'information, pas de le masquer sous les fioritures.

Le fond

Cette première publication doit être montrée. Pourquoi ? Pour se faire mousser ? Oui, mais surtout pour dire aux autres : « regarde, c'est super simple, tu as trois balises[4] à connaître, et hop, tu sais publier ».

C'est ainsi, par cette émulation (la course à la publication d'article), qu'il y a dans le SPIP base de connaissances de mon ex-équipe d'externalisation maintenant plus de cinq cents articles, en un peu plus de deux ans. Même les plus irréductibles de la documentation s'y sont mis. Comptons aussi pour parfaire le tableau une cinquantaine de mots-clés dont une grande partie comporte sa définition, une cinquantaine de rubriques, et finalement très peu de brèves.

Vos collègues ont aussi peut être quelque part des anti-sèches, souvent au format texte ou Word, voire sur un cahier. Il suffit de leur montrer qu'un simple copier-coller dans SPIP leur permet de publier facilement. C'est ainsi que la personne que j'ai remplacée chez mon client principal actuel m'a publié comme ça en quelques jours, sans faire de bruit, vingt-quatre articles. Il m'a suffit ensuite de les reprendre, de les enrichir et d'en faire de vrais articles agréables à lire.

Qui sait, l'inspiration vous viendra peut-être pour venir nous rejoindre dans ces colonnes. :)

Si vous manquez d'inspiration, vous pourrez toujours syndiquer en RSS des sites externes (votre serviteur a codé comme un cochon l'utilisation d'un proxy pour un site en intranet, code repris, corrigé et augmenté par le noyau dur de SPIP) pour animer votre site. Si vous avez de nombreux SPIP séparés, vous pouvez aussi les syndiquer entre eux. Comment faire des petits sans trop se fouler, un peu comme la cavalerie bancaire (qui est illégale, je le rappelle...)

L'important est d'abord de permettre aux autres de valoriser leur travail autant qu'on aime voir le sien valorisé une fois publié.

L'organisation du fond

Un autre avantage de SPIP, c'est que comme tout est en base de données, on peut casser la structure du site relativement facilement et changer les articles de rubrique très facilement (enfin, le plus rapide reste de passer des requêtes sur la base, parce que, sur ce point, l'interface n'est pas des plus aisée, il faut demander à modifier le contenu d'un article pour pouvoir le changer de rubrique, pas idéal, alors que les mots-clés s'attribuent sans passer par la case modification).

Exemple de hiérarchie SPIP, vue dans l'interface privée

On peut aussi attribuer des mots-clés aux articles, aux rubriques si on a activé cette possibilité, mots-clés regroupés dans des thèmes. Ces mots-clefs permettent d'adopter une structure de lecture beaucoup moins rigide que la structure arborescente des rubriques. On accède ainsi à une navigation différente, transverse de la navigation par rubriques.

Exemple de groupes de mots-clés

Attention, ces exemples restent des exemples. Il vous appartiendra d'adapter la structure du site à votre cas propre. D'expérience, l'erreur à ne pas commettre est de reproduire la structure des rubriques dans les mots-clés. Il faut trouver une manière différente de naviguer au travers de mots-clés.

La forme

Aussi, n'hésitez pas à adapter vos squelettes en fonction du type de navigation désirée, en utilisant à ce titre les mots-clés et les groupes de mots-clés.

Reportez-vous à la documentation de SPIP, qu'elle soit en ligne ou en PDF qu'on peut emmener partout.

Car si vous maîtrisez un tant soit peu HTML, personnaliser la forme de son SPIP, c'est aussi se l'approprier plus facilement et avoir envie d'y naviguer pour lire ce que les autres ont pu écrire.

Nous ne détaillerons pas ici la façon de faire, la communauté SPIP est très active sur le sujet, et il me serait idiot de les paraphraser.

Le moteur de recherche

Un dernier truc : le moteur de recherche indexe le contenu au fur et à mesure des visites, pour éviter une surcharge des serveurs web en environnement mutualisé. Il se peut donc que le site ne soit pas intégralement indexé, ce qui fait mauvais effet lors d'une démo. ;-) Plutôt que de passer un wget sur l'ensemble du site de façon à voir le fichier spip/ecrire/data/.index se vider, ce qui pouvait prendre un certain nombre d'itérations jusqu'à achèvement, une page dédiée existe maintenant. Cette page, spip/ecrire/admin_index.php3, n'est pas accessible par un lien depuis l'interface privée. Il vous faudra donc en taper l'URL dans votre navigateur. Avec quelques rechargements successifs, toutes les barres devraient passer au vert : à vous le moteur de recherche !

Page de réindexation de SPIP

Oh, j'allais oublier aussi : si vous avez un peu de puissance, pensez à réduire les délais de mise en cache à une faible valeur si vous voulez avoir un site reflétant toujours le contenu.

Refilez le virus aux autres

Vous n'êtes pas forcément la seule équipe à vouloir centraliser la documentation. C'est comme cela que trois autres SPIP internes ont été montés par d'autres que nous pour leurs besoins propres, et que d'autres se sont montés chez nos clients par des gens qui sont passés chez nous et ont repris le principe.

Pour les utilisateurs de Internet Explorer

Si vous êtes graphomane, utilisateur de vi[m], et parce que vous n'avez pas le choix utilisateur de IE, évitez de rédiger vos longs articles directement dans le champ de saisie de la partie privée de SPIP. En effet, le TEXTAREA sous IE a la désagréable habitude de se vider dès que vous appuyez sur ESC... Je parle d'expérience, avant l'arrivée des Mozilla et autres Firefox stables.

Avant de faire Ctrl-Z, ce qui restaure le texte disparu, vous aurez largement eu le temps de paniquer et de chercher dans une autre direction.

Conclusion, passez d'abord par un éditeur de texte normal. Au pire, utilisez le modèle Word[6] avec sa macro de conversion vers SPIP, ou encore écrivez en POD avec votre éditeur préféré, et convertissez ensuite (avec Pod::POM::View::SPIP[7], qui est encore loin d'être parfait).

Production : Travail en équipe et documentation

Chapeau

Travail en équipe et documentation

Un homme à abattre : le héros