Production des fichiers d’aide

Cet aide en ligne est construite localement par SPIP à partir de pages HTML fournies par un serveur d’aide, téléchargées et mises en cache sur le site client. Nous appelons fichiers d’aide les pages HTML qui sont téléchargées par SPIP à partir du serveur d’aide.

À l’heure actuelle, ces fichiers d’aide de SPIP sont produits sur www.spip.net à partir d’articles d’aide (article au sens de SPIP), plusieurs articles d’aide étant utilisés pour générer un fichier d’aide.
Plugins SPIP est aussi un serveur d’aide pour certains plugins comme PlugOnet et sjCycle2 en attendant de décider si il est judicieux d’étendre cette option à tous les plugins.

Les fichiers d’aide de SPIP sont donc stockés sur http://www.spip.net comme résultat de la compilation du squelette aide.html qui boucle sur tous les articles de la rubrique d’aide correspondant à la langue demandée.

Nom des fichiers d’aide

Il y a un fichier par langue, qui est nommé de la forme fr-aide.html où fr représente le code langue.

On pourra aller consulter un de ces fichiers pour y voir sa structure HTML, par exemple http://www.spip.net/aide/fr-aide.html.

Structure des fichiers d’aide

L’aide en ligne est structurée en deux niveaux : des blocs (Installation de SPIP, Les articles...) définis avec des titres de niveaux 1 (balises <h1>...</h1>) divisés en plusieurs sections (Régler les droits d’accès, Les Raccourcis typographiques...) définies avec des titres de niveau 2 (balises <h2>...</h2>).

À chaque section est associée une entrée d’aide, c’est-à-dire un texte explicatif, qui peut lui même être structuré avec des intertitres de niveau 3 (balises <h3>...</h3>).

Chaque section dispose d’un identifiant unique, commun à toutes les langues, permettant une navigation à travers la documentation. Cet identifiant est renseigné directement dans le code HTML de la page, sous la forme <h2>identifiant/Titre de la section en clair</h2>. Par exemple : <h2>raccourcis/Les raccourcis typographiques</h2>.

Présentation des fichiers d’aide par SPIP

L’aide en ligne n’est pas embarquée par SPIP : lorsque l’on souhaite visualiser l’aide en ligne depuis l’espace privé, SPIP télécharge une première fois les fichiers d’aide depuis le serveur d’aide et les stocke dans le cache pour les utilisations ultérieures.

Le fait de ne pas embarquer l’aide en ligne présente plusieurs avantages, notamment d’alléger les archives contenant le code, mais aussi de pouvoir gérer la rédaction et la traduction de l’aide en ligne indépendamment de l’écriture du code. Certains ont soulevé néanmoins que cela posait problème pour les sites situés par exemple sur un intranet sans accès internet. Il faudrait éventuellement discuter de la faisabilité d’un système permettant de générer une archive ZIP des fichiers d’aide qui pourraient alors être installés localement. Cependant, cela serait à voir dans un second temps, une fois l’aide en ligne réorganisée.

Le fichier d’aide est structuré pour présenter sur la colonne de gauche l’arborescence de l’aide (blocs et sections) et sur la droite afficher uniquement l’entrée d’aide correspondant à la section demandée.

Pour un exemple en SPIP 2.1, on peut consulter directement cette adresse : http://www.spip.net/aide/.

En SPIP 3, l’interface a légèrement évolué. Si on clique sur le lien Aide en haut de page, l’aide sera affichée dans une modalbox. Si on demande à ouvrir le lien dans un nouvel onglet, l’aide est affichée dans une page distincte avec le bandeau et le pied de page commun aux autres pages. Par ailleurs, les cadres ont été abandonnés.

Le titre de la section n’est pas répété au début de la page. De fait, les titres de niveaux 3 sont souvent utilisés en guise de titre de la page (exemple : Choisir la rubrique) et non pour définir une structure interne à la section (comme Les raccourcis typographiques).

En répétant le titre de la section en tant que titre de page, les titres de niveau 3 pourraient être réservés à la structure interne de la section, ce qui permettrait par exemple de proposer en début de page un bloc d’accès direct (une table des matières) pour accéder rapidement à un point donné, ce qui serait bien utile sur des sections souvent consultées comme les raccourcis typographiques.

Rédaction de l’aide en ligne sur spip.net

Pour le moment, la rédaction de l’aide en ligne de SPIP est gérée sur le site http://www.spip.net dans un secteur dédié intitulé Aide en ligne. Il est organisé avec une rubrique par langue - dont le titre est xx-aide.html - et dans chaque rubrique, un article par bloc, le titre de l’article correspondant au nom du bloc et le texte de l’article au contenu du bloc (sections et entrées). Les titres sont numérotés afin de définir l’ordre des blocs, l’ordre des sections étant déterminé quant à lui par l’ordre de leur apparition dans le texte de l’article.

Du fait du format spécifique des fichiers d’aide, le contenu des articles n’utilise pas uniquement la syntaxe SPIP. Ainsi, les titres de section doivent être renseignés avec des balises <h2>. Par exemple : <h2>rubhier/Une structure hiérarchisée</h2>

Limite : les rédacteurs/traducteurs de fichier d’aide doivent apprendre cette syntaxe particulière. Par ailleurs, c’est à eux qu’il revient de vérifier que l’arborescence au sein d’un bloc et que les identifiants sont bien les mêmes entre les différentes langues.

Les images ne sont pas gérées en tant que documents joints mais sont indiquées en HTML pur. Exemple : <CENTER><IMG SRC="AIDE/fr/rubhier-1.gif" BORDER=0 ></CENTER>

Une capture d’écran n’est pas directement accessible pour un rédacteur/traducteur. Or, si dans certains cas on peut réutiliser la même image dans plusieurs langues, il peut être aussi pertinent de changer l’image lorsque la capture d’écran contient du texte. Utiliser les documents joints (qui maintenant peuvent être joints à plusieurs articles) permet de rester sur un système connu des rédacteurs et qui leur est accessible. Cela règle aussi le problème de la profondeur des URL (actuellement on ne peut pas visionner les images dans l’interface de rédaction) puisqu’elles seront calculées automatiquement.

De même, les liens entre différentes sections de la documentation sont indiqués en dur. Exemple :

L'installation d'images pour ce logo de rubrique se déroule 
exactement de la même façon que pour le <A 
HREF="./?exec=aide_index&aide=logoart" TARGET="_top">logo d'un 
article</A>.

Il faudrait prévoir un mécanisme plus générique et conforme aux usages. Par exemple : [->aide:logoart]. Cela permettrait d’ailleurs que l’URL soit traitée différemment selon les contextes (présentation de l’aide sur un site web, intégrée dans SPIP, etc..) et puisse gérer la redirection vers une autre langue si l’aide n’est pas disponible dans la langue choisie.

Extension de l’aide en ligne

À partir de SPIP 2.1, il est possible d’étendre l’aide en ligne. Ce système est décrit sur spip.net. Néanmoins, à ce jour peu de plugins y ont eu recours.

Article détaillé : Étendre l’aide en ligne

Pour cela, il faut déclarer l’URL d’un serveur d’aide dans mes_options.php</php> via la globale <code>help_server. Par exemple : $GLOBALS['help_server'][] = 'http://mon.site.net/aide/';

SPIP ira alors rechercher des fichiers à partir de cette URL, par exemple pour le fichier d’aide en Français : http://mon.site.net/aide/fr-aide.html.

Limites : en utilisant cette convention de nommage, il n’est pas possible de produire directement un fichier de langue à partir d’un squelette SPIP dont l’URL serait de la forme spip.php?page=aide&lang=fr. Cela signifie que sur le serveur qui héberge les fichiers de langue il faut soit fournir des fichiers HTML statiques, soit mettre en place un système de réécriture d’URL spécifique (fichier .htaccess).

Par ailleurs, sur un site qui générerait plusieurs fichiers d’aide (pour différents plugins par exemple), il faudrait mettre en place des URL de la forme http://aide.spip.net/aide/pluginA/fr-aide.html et http://aide.spip.net/aide/pluginB/fr-aide.html.

Le système pourrait évoluer pour pouvoir spécifier par exemple un pattern (par exemple : http://mon.site.net/spip.php?page=aide&lang=@lang@ ; SPIP remplaçant alors @lang@ dans le pattern.

Il est possible de compléter une section (par exemple les Raccourcis typographiques), SPIP fusionnant alors le texte des deux entrées pour produire la section complète.

Il est également possible de fournir un bloc personnalisé avec ses sections additionnelles.

La documentation ne mentionne pas la possibilité d’ajouter une section à un bloc déjà existant.

Après un test rapide sous SPIP 3 beta (le 19 novembre), il s’est avéré :

• que l’ajout d’une section à un bloc existant a pu se faire sans problème
• par contre, la fonction permettant d’ajouter une entrée à une section déjà existante a posé problème (double entrée si consistante du nom de l’identifiant, écrasement de la section si nom de section non consistant mais identifiant identique).

Il n’est pas précisé si les fichiers d’aide doivent être encodés en UTF-8 (même si on peut le supposer), d’autant plus que l’encodage n’est pas indiqué dans l’en-tête des fichiers HTML.

Il serait pertinent de clarifier ce point et de poser l’UTF-8 comme obligatoire pour les fichiers d’aide.

Autres limites du système actuel

Versions de l’aide en ligne

L’organisation actuelle de la rédaction de l’aide en ligne sur spip.net ne permets pas de prendre en compte plusieurs versions de cette aide en ligne. Or, du fait de ses évolutions, l’aide en ligne pour SPIP 2.1 n’est pas la même que celle requise pour SPIP 3, ou celle des futures versions (3.1, 4...) encore à inventer avec tendresse. Or, l’aide en ligne sur un site en 2.1 ne doit pas présenter des fonctionnalités de SPIP 3, tout comme sous SPIP 3, il ne faut plus présenter des fonctionnalités qui n’existent plus (comme l’interface simplifiée). L’aide actuelle est d’ailleurs, et tout naturellement, vieillissante et les captures d’écran ne correspondent plus à situation actuelle. Certaines fonctionnalités ont disparu (comme la correction orthographique). Et pas un seul article sur la gestion des plugins !

Il faut donc pouvoir disposer d’un système de versioning.

Découpage de l’aide en ligne et réorganisation

Avec SPIP 3, l’écureuil a été mis au régime. De nombreuses fonctionnalités ont été déportées dans des plugins (brèves, forum, mots clés, révisions...). Or, si les plugins correspondants ne sont pas activés, il n’y a aucune raison pour que l’aide en ligne présente ces fonctionnalités. Pourquoi afficher une présentation des brèves si cette fonctionnalité n’est pas présente. Pour être efficace, une aide en ligne ne doit porter que sur les fonctionnalités disponibles.

Avec le découpage du core en plugins/extensions, l’aide en ligne doit elle aussi être réorganisée en conséquence. Autrement dit, l’aide en ligne fournit par le core doit se limiter strictement aux fonctionnalités du core. Aux plugins/extensions d’indiquer les fichiers d’aide les concernant pour produire une aide en ligne correspondant uniquement aux plugins/extensions actifs.

Ce découpage pourra être l’occasion de procéder à une réorganisation de l’aide. Ainsi, les raccourcis typographiques ne devraient pas être ranger dans le bloc Article. Ils sont partagés par tous les objets. D’autre part, ils méritent à eux seuls de constituer un bloc, de même que les modèles.

Autorisations

On peut considérer qu’une bonne aide contextuelle est, entre autres, de ne fournir que les informations pertinentes qui concernent un utilisateur donné. Il est donc préférable de masquer ce qui le concerne pas afin de lui permettre d’accéder directement à l’essentiel.

Un rédacteur, à la différence du webmaster, n’a pas besoin de voir les entrées consacrées aux droits d’accès des répertoires ou à l’installation de SPIP [1].

De même, pourquoi lui présenter Sur-titre, sous-titre, chapo et post-scriptum si on les a désactivés ?

Il faudrait pouvoir indiquer des conditions à remplir pour voir telle ou telle section, par exemple au travers d’une extension des autorisations ou un autre système.

Ordre des blocs et des sections

Au niveau de l’aide en ligne hébergée sur spip.net, l’ordre des blocs est déterminé par le numéro du titre. Ce numéro est utilisé pour produire le fichier d’aide (fr-aide.html) mais le rang est supprimé de ce fichier (application du filtre supprimer_numero). Au niveau de SPIP, lorsque la fusion des fichiers d’aide est réalisée, l’ordre de l’aide finale est dépendante de l’ordre dans lequel les fichiers sont fusionnés. Il devient dès lors difficile de produire un ordre cohérent, par exemple pour un bloc dont les sections sont fournies par trois plugins différents.

Il serait possible d’envisager que le numéro des titres des blocs et des sections (quand ils existent) soient toujours présents dans les fichiers d’aide, le filtre supprimer_numero étant appliqué par SPIP au moment de la fusion.

Dans le cadre d’une aide en ligne produite à partir de plusieurs sources/paquets, il faudrait pouvoir connaître la langue de référence de chaque paquet (qui ne sera pas toujours le français. En effet, si une entrée d’aide n’est pas disponible dans la langue demandée, il faut pouvoir proposer l’entrée en question dans sa langue de référence.