Wikini

OrganisationDeLaDocumentationDeWikiNi

PagePrincipale :: DerniersChangements :: DerniersCommentaires :: ParametresUtilisateur :: Vous êtes ec2-44-220-245-254.compute-1.amazonaws.com
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 :

Périmètre

Mais de quoi parle-t-on au juste ? Voyons ce qui peut prétendre à être la documentation de WikiNi :
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 :

Je suis un développeur :

La documentation doit être la plus propre possible. Aussi il me paraît important de séparer :


Solutions


Solution 0 : une doc particulière à chaque version de WikiNi


Avantages :

Inconvénients :

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

Exemples :











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 :

Avantages :

Inconvénients :

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.

Avantages de cette solution :
Effet de bord :
-- ProgFou

Inconvénients :

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

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

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 :
"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 :
-- 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 :
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 ?
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

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

Je pense que :
-- 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



Il n'y a pas de commentaire sur cette page. [Afficher commentaires/formulaire]