Carnet Wiki

Table ronde documentation 22 juillet

Version 15 — Février 2017 RastaPopoulos

I. Préambule : “la doc, c’est quoi au juste ?

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

II. La Doc du code

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 :

  • doc.spip.org
  • programmer.spip.net
  • spip.net

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é existant 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)

Voir aussi l’article : Documentation des APIs de SPIP

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 !

III. Faire évoluer spip.net

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

  • Image austère
  • Site de doc

b) Faible visibilité de l’ensemble de la galaxie

  • Pas de visibilité des autres sites
  • Pas de boussole

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

  • Premier contact avec spip
  • Présentation de la solution
  • Doc du « logiciel »

2. Site portail

  • Portail orientation
  • Accès à la communauté
  • Accès à la documentation
  • Accès aux contributions

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

  • Il faut une connexion pour rapatrier l’aide en ligne (vidée avec le cache)
  • Elle n’est pas versionnée on récupère des infos qui datent de la 1.8

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

<blockquote class="spip">

« 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

<blockquote class="spip">

« 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 ? »

</blockquote>

-> 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

IV. Questions de Méthodologie

A. Structure générale cible de la doc de spip

  • Portail - spip.net
  • Utiliser.spip.net
  • Intégrer.spip.net
  • Programmer.spip.net
  • Doc.spip.net (automatisé)

(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 :

  • Soit en créant un secteur par version
  • Soit en clonant le site pour modifier le contenu pour la version suivante (solution choisie par mathieu pour programmer)

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

  • Migration
  • Réécriture / maj
  • Production de nouveau contenu

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

  • Glossaire
  • Aide
  • Traduction

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

  • programmer.spip.net
  • utiliser.spip.net
  • intégrer.spip.net

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

V. Prochaines étapes et organisation

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 :

  • Alex
  • Arnault
  • denisb
  • Dani
  • Eric
  • George
  • James
  • Klaus
  • Maïeul
  • Marcimat
  • Rastapopoulos
  • Nat33

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 publié par rastapopoulos a été déplacé dans cet espace du carnet.
(infos sur comment drupal.org a été refait avec la communauté : http://markboultondesign.com/projects/drupalorg)

B. Prochaines étapes

1. Valider la structure

  • Des different sites : Que met-on dans les différents sites ? Qu’entendons nous par programmer et par intégrer ? Faire des boucles SPIP est-ce programmer ? > peut-être ecrire un article de présentation des différents sites, histoire de :
    • être au clair lorsque l’on ecrira le contenu
    • fournir un élèment pour l’utilisateurs

Proposition : chacun écrit un projet de structure, puis un comité exterieure à l’équipe rédactionelle pour éviter les conflits et les tournes en rond les lis et propose soit d’en prendre un, soit une synthèse.

échéance : mi novembre

2. Déployer

Une fois la structure validée des sites validées, il faut reflechir à sa transposition en terme de structure du contenu SPIP. Autrement dit : qu’est qui est de l’article, qu’est ce qui est est de la rubrique ? Dans le cas précis, on peut même se demander s’il n’est pas possible passer à une structure avec uniquement des pages imbriquées ?

Une fois validée cette structure (début dec), on met en œuvre les sites, en mettant des articles "vides", qu’on remplit.

Sur les sites qui hebergent actuellement de la doc, on met en place un système de mot clef pour marquer qu’un contenu a été "transféré".

Se pose la question de la génération auto de doc à partir du code source de SPIP, et notamment ce qui relèvent des "filtres" de ce qui releves des fonctions de l’API PHP. Est-ce que Eric et Marcimat pourrait mettre les liens vers les articles résumant leurs propositions ?

En // on crée, modifie les squelettes / styles pour avoir une présentation sous forme de livre qui permette :
-  une navigation aisée aux seins de chaque site
-  un reconnaissance aisée des ≠ sites
-  une relation entre les sites, voire un portail ?

Finaliser

Lorqu’on estime que c’est publiable (fin juin 2013 ?), on publie + on génere les versions PDFs