Version 9 — Septembre 2012 — RastaPopoulos
Quand on parle de la doc de spip, il faut distinguer la documentation :
• du code -> doc des fonctions de spip, comment les utiliser etc... doc du développement de plugins
• de l’interface -> concerne les utilisateurs de l’interface, rédacteurs, admin etc
• du langage -> concerne ceux qui écrivent des squelettes, les intégrateurs
• Du logiciel -> présentation du logiciel, des fonctionnalités et des versions
A. La doc du code = la doc des fonctions
Du point de vue de l’architecture, il est fondamental de définir les fonctions et la façon de les utiliser.
La partie visible, ce sont les fonctions les plus utilisées. Pour les fonctions qui constituent des points d’entrée on est obligé de maintenir la compatibilité.
Toutefois, toutes les fonctions ne sont pas censées devenir des points d’entrée vers l’extérieur.
Ce n’est pas souhaitable car cela impose des contraintes lourdes de développement pour l’évolution en termes de maintenance et de compatibilité.
La première question à se poser avant de documenter une fonction c’est « est-ce qu’on veut la rendre publique ou pas ».
B. Etat des lieux : un gros travail de maj et d’écriture est nécessaire
1. Insuffisance de la doc et besoin de maj
En ce qui concerne le code, les fonctions sont insuffisamment documentées pour le moment.
2. Dispersion de la doc du code dans plusieurs sites :
Si on prend l’exemple de la documentation d’une fonction filtre, il faudrait que la doc concernant cette fonction ne se trouve qu’à un seul endroit.
Il faut faire des liens entre les sites programmer.spip.net, spip.net et doc.spip.org
C. Le projet de refonte de doc.spip.org
1. Historique
Doc.spip.org a été conçu au départ, par Piif pour faciliter l’accès à la documentation des fonctions et permettre de récupérer de façon automatique les commentaires inclus dans le code des fonctions
http://doc.spip.org/
Le site a périclité pour plusieurs raisons :
Il a été préconisé par ESJ de plutôt produire une code facile à comprendre et de limiter les commentaires, donc on a produit moins de commentaires
D’autre part le mécanisme d’alimentation automatique du site est cassé aujourd’hui et le site n’est plus à jour ni maintenu par Piif.
Il semble aujourd’hui plus pertinent de redévelopper le site en s’appuyant sur la norme phpdoc.
2. Le chantier Documentation du code – Refonte de spip.org
Eric, Denis et Mathieu ont commencé à réfléchir et travailler sur le chantier de la documentation du code de spip.
L’idée est de réparer doc.spip.org, un système automatique d’alimentation d’un site SPIP qui documente toutes les fonctions en s’appuyant sur la convention d’écriture de commentaires phpDoc.
On part de la même entrée : le code php contenu par les fichiers, explorer par un script du marché plutôt que fait-maison.
On peut modifier dans le code les descriptions : l’idée étant de mettre à jour les commentaires dans code à partir des modifications effectuées sur le site.
Actuellement il y a une interface. On utilise des articles liés à une fonction.
Cela permet à des personnes ne participant pas au dépôt de code dans le noyau de SPIP de le documenter, par exemple l’API SQL...
Dans programmer.spip.net, il y a quelques articles de présentation, c’est bien de les récupérer
« On documente et on extrait la documentation »
L’idée n’est pas de réimporter toute la doc dans le code.
On peut ne réimporter que l’entête de la fonction (code formaté selon la norme phpDoc)
D. Programmer.spip.net
La vocation de programmer.spip.net c’est plutôt d’apporter des explications complémentaires aux développeurs sur la façon de développer un plugin.
On est plus proche de la collection de tutoriels, du « comment faire »
Pour migrer programmer en version 3, Mathieu a simplement cloné la base et refait une installation. La version 2 est maintenant gelée.
Voir en ligne : http://programmer3.spip.net
Toutes les modifications nécessaires peuvent ainsi être apportées sans problématique d’historique.
Le travail de mise à jour est actuellement en cours. Ne pas hésiter à participer !
A. Etat des lieux
Spip.net rassemble actuellement « L’autre doc »
On y trouve également la documentation sur le développement des squelettes (plutôt destinée aux intégrateurs), la documentation de l’interface, mais aussi la documentation du logiciel (spip qu’est ce que c’est , évolution, versions)
Spip.net est aussi le site officiel de SPIP, mais c’est pour l’instant presqu’exclusivement un site de documentation
1. Les points forts
Information riche et complète, précieuse, multilingue
L’historique permet de proposer une documentation aux webmestres quelle que soit la version de leur site
2. Les difficultés / lacunes actuelles spip.net
a) Présentation peu séduisante de la solution
b) Faible visibilité de l’ensemble de la galaxie
c) Manque de lisibilité de l’information proposée par le site
Une doc très riche, très complète, précieuse mais les clés d’entrées semblent réservées aux initiés (ceux qui ont l’habitude, qui savent où sont les informations)
Problème de lisibilité de l’organisation de l’information, on trouve l’info grâce au moteur de recherche, au glossaire (si on connait)
L’empilage des différentes couches historiques nuit également à la clarté de l’information présentée à l’utilisateur
d) Manque de contributeurs volontaires
Il est à la fois facile de participer à la mise à jour de spip.net mais difficile de s’y retrouver, de comprendre les conventions, de se sentir habilité. Ce processus n’est pas documenté.
La préservation de l’historique dans la doc vivante peut devenir un frein à la mise à jour
B. Quelle vocation pour spip.net ?
A quels besoins essentiels devrait répondre spip.net
1. Site officiel
2. Site portail
C. Les contraintes et/ou spécificités sur spip.net
La perspective d’une réorganisation de spip.net nécessite de prendre en considération un certain nombre de problématiques et/ou contraintes spécifiques
1. les traductions
Un secteur par langue, si on modifie la structure il faut déployer les changements pour toutes les langues
2. Les versions
Le parti a été pris au départ d’incrémenter la documentation pour chaque nouvelle version, en conservant l’historique
3. Aide en ligne
a) Les caractéristiques
b) Les propositions
<blockquote class="spip">« On pourrait avoir une nouvelle version de l’aide ? »
</blockquote>
- > Attention elle est traduite dans toutes les langues, si on la versionne, il faut la repasser entièrement sur trad langue
Voir système de report (?)
- > Attention cela risque de sensiblement alourdir les processus de livraison de nouvelles versions
« Si utiliser.spip.net est exportable en pdf, on pourrait avoir un fichier d’aide complet, disponible en local et l’aide en ligne deviendra moins nécessaire ? »
</blockquote>
- > Attention ce qui fait la spécificité de l’aide en ligne c’est que c’est une aide HyperText contextuelle en ligne, traduite dans toutes les langues
« Est-ce que le compagnon ne pourrait pas être aménagé pour remplacer l’aide ? On est dans le registre de l’aide ... »
</blockquote>-> Le compagnon a uniquement pour vocation d’accompagner les premiers pas de l’utilisateur. Il est censé disparaitre une fois qu’il a délivré son message et qu’il a été fermé.
<blockquote class="spip">« L’aide en ligne est principalement utilisée pour les raccourcis typo -> Page memento en local.
Une page en local, ce serait bien ? »
-> Une partie de l’aide est consacrée à l’installation et doit pouvoir être appelable pendant la procédure d’installation
<blockquote class="spip">« Ce serait intéressant de décliner le compagnon pour accompagner l’utilisateur pour intégrer un document dans un article. »
</blockquote>
- >Il faudrait plutôt revoir l’ergonomie de cette fonctionnalité si ce n’est pas intuitivement correctement compris par les utilisateurs.
D. Le Chantier sur la réorganisation de spip.net
Rastapopoulos à travaillé il y a plusieurs mois sur l’organisation de l’information sur spip net il avait publié le résultat de ses réflexions et travaux sur le carnet de contrib et sollicité des avis sur spip-team. La démarche a reçu peu d’écho à ce moment là.
Voir en ligne : http://contrib.spip.net/Refonte-de-spip-net
Rasta est parti d’une analyse de spip.net dans un premier temps, et a ensuite étudié les sites des portails d’autres éditeurs de logiciels libres.
On peut ainsi faire ressortir un certain nombre de constantes dont on peut s’inspirer pour réaménager le plan et la navigation
Un nouveau plan est proposé sur le wiki , précisant les éléments ajoutés ou simplement renommés et/ou déplacés.
Certains liens pointent vers d’autres sites de la galaxie.
Il s’agit d’une proposition, les participants pourront l’analyser à tête reposée et faire part de leurs observations
E. Sortir la doc de spip.net ?
Sortir la doc de spip.net permettrait d’organiser plus clairement le site en tant que portail officiel de spip
On pourrait déployer 2 sites
Intégrer.spip.net pour les intégrateurs et développeurs de squelettes
Utiliser.spip.net pour les utilisateurs de l’interface ; rédacteurs, administrateurs et webmestres
A. Structure générale cible de la doc de spip
(Il y a certains sujets qui n’appartiennent pas clairement à une activité détérminée, il faut decider sur quel site les mettre. Par ex. la mutualisation, ce n’est pas vraiment du dévelopement ni vraiment de l’integration).
B. Migration
1. Comment faire évoluer les sites ensuite à chaque sortie de nouvelle version ?
On peut faire une « une branche » par nouvelle version pour reprendre l’ensemble puis apporter les modifications nécessaires :
2. Comment préparer la migration de spip.net ?
a) Maintenir le site d’origine pendant les travaux
Garder une copie intègre du site d’origine
Si l’on s’attaque au projet de refonte se spip.net en tant que portail , il sera nécessaire de disposer d’un outil de suivi de migration
b) Créer les sites de doc : integrer et utiliser
(1) Préparer la structure de chaque site
(2) Déployer la documentation
c) Créer le nouveau portail
Installer un nouveau site et Préparer la structure avant la migration
Pour spip net, si on veut envisager de réorganiser l’information, il semble nécessaire de commencer par préparer la structure.
On installe le portail et on prépare la structure
d) Basculer spip.net sur le nouveau portail
e) Maintenir archives.spip.net pour l’historique
3. Communiquer en amont avec les traducteurs
On pourrait déjà annoncer aux traducteurs qu’un travail est amorcé.
Et ensuite leur demander de stopper les publications au moment ou on clone la base
4. Trouver une solution pour les points délicats
5. Prendre en compte le référencement (rajout nat33)
Spip a été extrêmement bien référencé par google.
Il va falloir gérer le dispatch de tous ces liens et des back links peut etre page par page
C. Squelettes et design des sites
1. Unifier le format des sites de documentations programmer / utiliser / intégrer
La question du format des différentes documentations se pose également
Marcimat explique qu’il serait intéressant d’ utiliser un même squelette pour les différents sites. Cela permettrait d’assurer une certaine cohérence graphique et à mutualiser le travail de maintenance et d’évolution
On pourrait simplement décliner un code couleur pour différencier chaque site.
Le squelette de programmer pourrait tout à fait être décliné avec un code couleur différent pour
L’avantage de ce squelette est qu’il est conçu pour pouvoir être transformé en livre, et que cette fonctionnalité est tout aussi pertinente pour les doc intégrer et utiliser.
La question de la gestion des langues est soulevée.
LE squelette est conçu pour permettre de gérer plusieurs traductions, mais programmé a principalement été traduit en anglais, mais pas dans les autres langues.
C’est surtout pour utiliser.spip.net qu’il sera important de proposer d’autres traductions
2. Refonte de spip.net portail
Au dela de la structure il faudra travailler sur l’ergonomie et le design de spip.net /portail
Partir sur une base Z
A. Les Outils
1. Une liste dédiée
James voit avec Fil pour créer une liste dédiée
Les participants seront inscrits :
http://listes.rezo.net/mailman/listinfo/spip-doc
2. Compte rendu de la réunion
Nathalie se charge de rédiger le compte rendu et de le diffuser aux participants
3. Un espace de travail collaboratif
Une rubrique dédiée a été créée dans le carnet : http://contrib.spip.net/Chantier-documentation-2012
Le document de travail L document de travail publié par rastapopoulos a été déplacé dans cet espace du carnet.
B. Prochaines étapes
1. Valider la structure
à préciser
2. Déployer