Cette page a pour but de définir l'organisation de la documentation du logiciel
WikiNi : tout ce qui est actuellement publié dans
LaDocumentation.
Elle n'a pas pour but de définir l'organisation du wiki et/ou celle du projet.
On fait un joyeux mélange entre ce qui ressort de
WikiNi 0.4.1rc et
WikiNi 0.1.3 :
- faut-il créer des pages pour chaque version avec des redirections des pages génériques vers les pages relatives à la version stable ?
- [Très bonne remarque !! En revanche, doubler (voir plus) les pages à chaque fois risque d'être lourd... Je propose deux choses : d'une part avoir deux pages WikiNi01x? et WikiNi04x? sur lesquelles on pourra recenser des pages qui ne concernent que ces versions respectives, d'autre part se forcer à indiquer systématiquement la version WikiNi (mineur, pas patch, donc 0.4 ou 0.1) en tête (ou pied) de chaque discussion sur une fonctionnalité de WikiNi. -- ProgFou]
Périmètre
Mais de quoi parle-t-on au juste ? Voyons ce qui peut prétendre à être la documentation de
WikiNi :
- 17 actions figurent actuellement dans la ListeDesActionsWikini
- 14 handlers (chaque handler ne faisant pas actuellement l'objet d'une page de doc)
- environ 17 pages pouvant éventuellement prétendre à faire partie de la doc officielle (ReglesDeFormatage, ListeDesActionsWikini, LaDocumentation, CommentModifierUnePage, CommentCreerUnePage, CommentChoisirUnNomDePageEfficace, CommentSupprimerUnePage, ToutLeMondePeutEcrire, DocumentationAdministrateurFonctionnel, AccessControl, DocumentationAdministrateurTechnique, DocumentationDeveloppeur, DocumentationGraphiste, CommentPersonnaliserGraphiquementWikiNiEn10Minutes, ValeursLimitesDeWikini, FaviconEtWikiNi, HeaderPhp, DocumentationFichierDeConfiguration) : à voir, il faudrait peut-être faire du tri...
Soit environ 48 pages de doc qu'il faut distinguer en plusieurs groupes :
J'estime qu'entre deux versions de
WikiNi il y a au moins la moitié sinon les deux tiers des pages de doc qui changent.
Nous parlons ici de la documentation de l'outil et non des autres types de doc qui sont hors périmètre. Par essence, la documentation de l'outil est livrée avec les ditributions de l'outil.
Hors périmètre
Ces documentations évoluent sur le site et ne sont pas livrées avec les distributions de
WikiNi.
Besoins
Je suis un utilisateur :
- Quand je télécharge WikiNi xxxx je veux pouvoir consulter la documentation qui concerne la version xxxx et pas les autres versions
- Je veux connaître les différences entre une version et la version suivante
- Je veux que la doc soit présente sur mon wiki
- Je veux que la doc WikiNi présente sur mon wiki soit mise à jour lorsque j'effectue une mise à jour de WikiNi
- Je veux que les modifications de la doc de WikiNi que j'ai personnellement effectuée sur mon wiki ne soit pas écrasées par la doc de la nouvelle version de WikiNi que je viens d'installer
- Je ne souhaite pas installer la doc de WikiNi sur mon wiki, mais seulement la consulter sur le site wikini.net
- Sur le site wikini.net, je ne souhaite consulter que la doc et pas toutes ces discussions de geek auxquelles je ne comprends rien et qui polluent ma lecture
Je suis un développeur :
- Où dois-je ranger la documentation sur cette fonction qui sera publiée dans la prochaine version de WikiNi ? comment dois-je appeler cette page ?
- Comment indiquer que cette fonction n'est pas encore disponible ?
- Au passage à la version suivante, dois-je effectuer un travail particulier sur la doc pour la voir publiée ?
La documentation doit être la plus propre possible. Aussi il me paraît important de séparer :
- ce qui ressort de la doc
- de ce qui ressort des discussions que nous pouvons avoir sur telle ou telle amélioration ou autre.
Solutions
Solution 0 : une doc particulière à chaque version de WikiNi
- chaque version de WikiNi possède une version complète de chaque documentation même si la documentation n'a pas changée
- chaque documentation de chaque version de WikiNi est préfixée par Doc et le numéro de la version : DocWikiNi013ActionRecentChanges?, DocWikiNi041ActionRecentChanges?, DocWikiNi013HandlerDiaporama?, etc.
- pour éviter les confusions, la documentation d'une fonction encore en développement est préfixée par "Dev" ou bien "Proposition" (par exemple toutes les propositions listées dans OuEnSommesNous) : DevActionRecentChanges?
Avantages :
- pour les utilisateurs de WikiNi, la mise à jour de wikini 0.x.x à 0.y.y n'écrase pas la documentation existante
- l'utilisateur peut personnaliser la documentation
- la documentation de WikiNi est plus stable, séparée des discussions et des propositions d'évolution
- l'utilisateur n'est pas pollué par des informations ne concernant pas sa version
- possibilité de mise en oeuvre sans délai
Inconvénients :
- multiplie le nombre de pages et de contenus sur wikini.net
- multiplie le nombre de pages chez les utilisateurs qui effectuent une mise à jour de WikiNi
- suggère de faire des "backports" lorsqu'il y a une erreur dans la documentation
Cette solution a ma préférence.
Cette solution n'empêche pas d'avoir en fin de chaque document un petit historique discret de la fonction du type :
- WikiNi 0.x.x : apparition de la fonction
- WikiNi 0.y.y : modification du paramètre "page"
- etc.
--
CharlesNepote
Exemples :
- Ex0DocWikiNi013ActionListPages?
- Ex0DocWikiNi041ActionListPages?
- Ex0DocWikiNi013ActionListUser?
- Ex0DocWikiNi041ActionListUser?
- Ex0DocWikiNi013ActionMyChanges?
- Ex0DocWikiNi041ActionMyChanges?
- Ex0DocWikiNi013ActionMyPages?
- Ex0DocWikiNi041ActionMyPages?
- Ex0DocWikiNi013ActionRecentChanges?
- Ex0DocWikiNi041ActionRecentChanges?
- Ex0DiscussionsActionRecentChanges?
- Ex0DocWikiNi013ActionRedirect?
- Ex0DocWikiNi041ActionRedirect?
- Ex0DiscussionsActionRedirect?
- Ex0DocWikiNi013ActionTextSearch?
- Ex0DocWikiNi041ActionTextSearch?
- Ex0DiscussionsActionTextSearch?
- Ex0DocWikiNi013ActionTrail?
- Ex0DocWikiNi041ActionTrail?
- Ex0DiscussionsActionTrail?
Cette solution est finalement retenue pour fabriquer la documentation. Elle sera mise en oeuvre progressivement. --
CharlesNepote
Solution 1
Le principe de cette solution est simple :
- chaque fonctionnalité fait l'objet d'un numéro de version : par exemple ActionRecentChanges1?, HandlerDiaporama06?, etc.
- chaque documentation de chaque version de WikiNi est préfixée par Doc et le numéro de la version : DocWikiNi013ActionRecentChanges?, DocWikiNi041ActionRecentChanges?, DocWikiNi013HandlerDiaporama?, etc.
- chaque page de documentation contient un include vers la documentation de la version correspondante : exemples :
- DocWikiNi013ActionRecentChanges? va contenir {{include page="ActionRecentChanges1}}
- DocWikiNi041ActionRecentChanges? va contenir {{include page="ActionRecentChanges1}} dans le cas où il n'y a pas eu d'évolution de RecentChanges?
- DocWikiNi013ActionRecentChanges? va contenir {{include page="ActionRecentChanges2}} dans le cas où il y a eu passage de la version 1 à la version 2 de RecentChanges?
- pour éviter les confusions, la documentation d'une fonction encore en développement est préfixée par "Dev" ou bien "Proposition" (par exemple toutes les propositions listées dans OuEnSommesNous) : DevActionRecentChanges?
Avantages :
- pour les utilisateurs de WikiNi, la mise à jour de wikini 0.x.x à 0.y.y n'écrase pas la documentation existante
- ne répète pas des contenus existant (à l'aide des "include")
- la documentation de WikiNi est plus stable, séparée des discussions et des propositions d'évolution
- l'utilisateur n'est pas pollué par des information ne concernant pas sa version
- possibilité de mise en oeuvre sans délai
Inconvénients :
- multiplie le nombre de page sur wikini.net
- alourdi la documentation en ajoutant un numéro de version pour chaque fichier ?
- multiplie le nombre de page chez les utilisateurs qui effectuent une mise à jour de WikiNi
- suggère de faire des "backports" lorsqu'il y a une erreur dans la documentation
Solution 2
Le principe de cette solution est simple aussi... ;-)
Elle se base sur le modèle utilisé dans la documentation PHP, avec quelques bémols.
- chaque fonctionnalité toujours présente fait l'objet d'une unique page : par exemple ActionRecentChanges
- chaque page de documentation commence par indiquer à partir de quelle version la fonctionnalité est disponible
- à l'intérieur de la page on trouve les détails concernant la fonctionnalité, avec indication de version pour certaine de ses options le cas échéant
- on renomme systématiquement les page de documentation sur les fonctionnalités supprimées : ActionDisparue? => ActionDisparueObsolete?
Avantages de cette solution :
- la documentation d'une fonctionnalité se fait toujours à un seul et même endroit
- on voit du premier coup d'oeil (première ligne) quelle version de WikiNi est nécessaire pour utiliser une fonctionnalité
- l'historique des options est conservée et facilement lisible tant par l'utilisateur que le développeur
Effet de bord :
- un développeur voit facilement quelle option est diponible par rapport à la version de WikiNi sur laquelle il travaille
- un administrateur peut nettoyer la documentation en supprimant les pages LIKE '%Obsolete'
--
ProgFou
Inconvénients :
- l'utilisateur est polué par des informations sur les anciennes versions dont il n'a que faire ; imprimer la doc lui demande trois fois plus de papier pour rien
- pour peu que l'administrateur supprime la référence à WikiNi en signature, l'utilisateur ne sait pas forcément quelle version de wikini il utilise
- lors d'une mise à jour de wikini, la doc précédente est écrasée (on peut éventuellement installer des révisions plutôt que de remplacer)
Que se passe-t-il lorsque je met à jour mon site en passant de
WikiNi 0.4.1 à 0.5.0 par exemple ?
Est-ce que la doc existante est écrasée (avec toutes les petites modifications que j'y avais apportées pour mes lecteurs) ?
--
CharlesNepote
- Selon le modèle d'origine oui. C'est plutôt logique pour la doc du logiciel même. Et si on a adapté le logiciel (code source et docs), on prendra garde à vérifier les différences avant de basculer (faire un diff et appliquer les différences). -- ProgFou
- Mais moi, utilisateur lambda, comment je sais qu'il faut éviter de modifier la doc installée sur mon WikiNi ? [On peut le préciser dans la doc elle-même et en profiter pour appeler à collaborer en ligne. -- ProgFou] Par ailleurs, je trouve que la documentation WikiNi n'est pas très bien écrite, j'ai réécris une page sur deux et je ne me souvient plus vraiment quelles pages... alors comment je fais ? -- CharlesNepote
- Tout dépend si on veut "forcer" le mode collaboratif (retour des utilisateurs) ou non. Quelqu'un qui veut travailler seul dans son coin devrait pouvoir l'assumer au moment d'une mise à jour (on peut éventuellement l'aider en mettant des outils à sa disposition : diff puis patch sur la doc). Quelqu'un qui veut améliorer les choses devrait donner du retour sur le site du projet, donc ici WikiniPointNet. C'est mon point de vue, et il n'engage que moi. -- ProgFou
Tu auras compris que, pour le moment, je ne suis vraiment pas séduit par ta solution... [Pas de problème : si c'était le cas on n'aurait pas besoin de discuter... Ce serait même un peu "fade"... ;-) --
ProgFou] elle me paraît être très orientée pour le développeur mais pas pour l'utilisateur final. La discussion reste ouverte. Je pense que c'est important d'avancer sur ce sujet parce qu'il y a de plus en plus de page qui deviennent illisibles du fait que l'on y mélange beaucoup de choses ; cf. par exemple les pages :
--
CharlesNepote
Discussions
Sous pages pour une meilleure lisibilité
On voit ici que la notion de sous pages permettrait une meilleure visibilité :
--
CharlesNepote
- Mhhh... Des révisions explicites (via les sous-pages) en plus des révisions implicites (dans la base)... Bof... Dans ce cas je proposerais plutôt autre chose : la possibilité de tag'er une page avec un numéro de révision, comme en CVS ; les versions tag'ées ne seraient jamais purgées. -- ProgFou
- Ouais ! c'est une bonne idée ça ! ça permettrait de figer un wiki à l'état qu'il a à une date donnée et de continuer à faire évoluer le wiki ensuite tout en pouvant retrouver facilement cette version. -- PiIf
Préfixes "Dev" ou "Proposition"
Que pensez-vous de mettre un peu d'ordre dans les pages en préfixant les proposition ou suggestions par l'un des choix suivants :
- "Dev" : pour indiquer le caractère de développement
- "Proposition" : indique qu'il ne s'agit que d'une proposition non encore intégrée
- "Suggestion"
- "Discussion"
"Proposition", quoiqu'un peu long, a ma préférence. Qu'en pensez-vous ?
--
CharlesNepote
Préfixes "hack" ou "évolution"
Certaines fonctions comme la
FonctionDeDiaporama doivent être adaptées si on souhaite les faire fonctionner sous
WikiNi 0.1.3-0.1... Il faut donc pouvoir documenter ces "hacks" sans pour autant laisser croire qu'il s'agit de la documentation officielle de
WikiNi 0.1.3. Je propose donc un préfixe "hack" ou "evolution" pour marquer ces pages. Par exemple :
- EvolutionWikiNi013HandlerDiaporama?
- ...
--
CharlesNepote
Pages taguées
À
mon avis, l'exemple précédent montre bien la limitation de cette méthode : on arrive à des titres à rallonge.
Par contre, le principe de
TaggerLesPages à la cvs permettrait de garder une doc unique, accessible par les débutants, tout en gardant la possibilité de retrouver les anciennes versions facilement, par exemple, pour consulter en ligne la doc d'une version antérieure.
Je verrai bien un truc de ce genre :
- wikini.net contient la doc de référence, avec un Tag DOC041 pour les pages de docs de la version 041, DOC013 pour la précédente, etc ...
- un batch peut sortir les pages etiquetée avec une version donnée pour en faire la doc inclue dans la distrib
- c'est également possible avec des solutions sans tag -- CharlesNepote
- oui, en se basant sur la date de révision, mais quid des docs qui évolueraient "trop vite" et seraient en avance sur la version stable en cours ? la notion de tag (révision marquée) simplifierait ce problème -- ProgFou
- non, pas en se basant sur la date de révision mais en se basant sur le nom de la page DocZZZZZ041? DocZZZZZ050?, etc. -- CharlesNepote
- dans une page donnée, on peut faire évoluer les pages sans risque de perdre des anciennes références, on a donc des pages qui ne parlent que d'une version à la fois => on gagne en clarté
- c'est également possible avec des solutions sans tag. C'est d'ailleurs ce que je propose en solution 0 et 1. -- CharlesNepote
- oui, mais en multipliant le nombre de pages du site, alors qu'avec des révisions marquées (qui seraient obligatoirement conservées) en base : pas de purge sur ces révisions) on n'aurait toujours qu'une seule page, pour laquelle on pourrait regarder les révisions pour voir les anciennes versions de la doc suivant les versions du logiciel -- ProgFou
- la multiplication des pages est un faux problème à mon sens ; il s'agit seulement de quelques dizaines de pages qui ne représentent pas grand chose au regard de la clarté de lecture -- CharlesNepote
- pour l'exemple du diaporama, on documente pour la version courante, et éventuellement, une page à part explique comment backporter, mais là, on est déjà dans le hack, pas dans la doc à intégrer dans la distrib.
Bien sur, tout ca nécessite de voir comment on pourrait créer une fonction pour
TaggerLesPages, et c'est pas immédiat :-( --
PiIf
ProgFou et
PiIf, comment voyez-vous l'accès aux pages taguées ? Comment l'utilisateur taguerai-t-il une page ?
- Il faudrait en discuter sur la page TaggerLesPages (que je renommerais plutôt en MarquerLesPages?). -- ProgFou
Personnellement je ne vois pas bien la façon dont on s'y prendrait. Les wikis existent depuis bientôt 10 ans et je ne connais pas d'outil qui gèrent les pages de cette façon. Cette façon de taguer des pages est peut-être naturelle pour un développeur mais elle me paraît délicate pour un non informaticien. Cela dit je suis ouvert à toute proposition ; il faudrait au moins décrire le principe fonctionnel. --
CharlesNepote
- Ce n'est qu'une idée comme ça en passant, mais elle risque de m'être bougrement utile sur mon site (qui vient de basculer en mode privé, hélas) : je prévois de permettre le marquage des pages afin d'indiquer quelles révisions peuvent être lisibles en public, une sorte de validation quoi... Mais ceci est une autre histoire... Dans ma solution (numéro 2), je n'utiliserais pas de marquage. -- ProgFou
Question doc particulière vs doc globale
Pour avoir une idée, je souhaite déjà qu'on puisse évaluer si les gens préfèrent (ajouter votre nom) :
- une doc particulière à chaque version de WikiNi (quelque soit la solution retenue (pages, tags, etc.)) : CharlesNepote, PiIf
- une doc globale mélangeant toutes les versions présentant toutes les fonctionnalités, avec indication de leur obsolescence ou de la version de WikiNi à partir desquelles elles sont disponibles : ProgFou
Je pense que :
- l'accroissement du nombre de page est un faux problème
- vouloir documenter toutes les versions d'une fonctionnalité en une page est illusoire : si je ne m'abuse, la doc PHP illusoirement construite sur ce principe, ne comporte pas de référence aux fonctions ayant été abandonnées entre PHP 2 et PHP 3... ni même de doc sur la prochaine version PHP 5
- utiliser des pages clairement distinctes n'empêche pas de faire référence à des versions précédentes
- la longueur des titres est accessoire par rapport à la non qualité de la doc actuelle
--
CharlesNepote
Proposition 3
Faire une page qui sera le menu exhaustif de la documentation de wikini SUR le site officiel wikini. Il manque en effet une page centralisant tous les liens un peu comme le resume fait au haut de cette page dans "perimetre".
Ne pas distribuer les docs avec la version de wikini, ou alors les distribuer en option. A la place se contenter de mettre par defaut dans la distribution une page linkant vers la page menu du site officiel wikini. Ainsi on a une doc toujours a jour!!! Pas besoin de l'actualiser sur son propre site. Ceux qui veulent la doc sur leur site pourront la telecharger en option.
Je propose cela parce que la doc s'est installée par defaut sur mon site et ca me bouffe de la place pour rien. Et comme l'effacage de tant de pages est un casse tete chinois voila.
Ah pour ce qui est de la page menu, un commentaire pour chaque page serait pas de trop, les noms wiki sont souvent insuffisants pour comprendre vraiment de quoi il retourne.
Production automatique de la doc
Il existe une solution rustisque et simple : faire un wget récursif sur une page listant la doc.
Maturité des discussions
Je pense que nous sommes arrivés à une certaine maturité sur le sujet, nous permettant de rédiger maintenant une synthèse sous la forme de la page suivante :
DocDeveloppeurOrganisationDeLaDocWikiNi. --
CharlesNepote