Re: RE : [sdx-developers] Systeme de documentation

[Pierrick Brihaye]

Salut,

>Oui, c'est ce que je voulais dire. Les documents seront vraiment
>DocBook.

On est d'accord :-)

Les conditions théoriques étant désormais claires, j'ai commencé à
travailler dans cette perspective en me faisant la main sur le
descriptif de l'installation sous Win98 qui m'a été demandé récemment
sur une autre liste ;-) Ayant désormais un beau fichier valide website,
je me pose quelques questions pratiques :

1er point : quelle DTD choisir ? dans la dernière distrib en date, la
2.1b1 que j'ai récupérée sur les conseils de Patrice, j'ai une DTD
website, une website-full et une website-custom ! Dans quelle mesure,
cette distrib est-elle une bêta ?

2ème point, probablement le plus important : docbook, c'est l'auberge
espagnole. Derrière les dizaines d'éléments de balisage, on peut mettre
la sémantique que l'on veut. Dans le texte que j'ai tapé, j'ai des tags
XML pour configurer SDX via Tomcat. Comment je dois les considérer :
comme des <sgmltag>, des <programlisting>, des <literal>... ? Dois-je
organiser mes fichiers/pages en <section> ?

Qui saura nous ("me", en fait ;-) mettre sur le bon chemin ? Peut-on
prévoir assez rapidement des "guidelines" pour documenter SDX de façon à
peu près cohérente ?

3ème point : doit-on prévoir un "dictionnaire SDX" pour éviter que des
réalités identiques soient nommées en des termes différents (ah, les
"requêtes de recherche" !) ? Faire de l'informatique francophone me
semble parfois un exercice très périlleux ;-))

4ème point : quel format pour les ID utilisées dans les fichiers ?

5ème point : où envoyer les fichiers des différents contributeurs ?
Comment organiser l'arborescence ? Le multilinguisme ?

6ème point : ne peut-on envisager des contributeurs qui ne soient pas
développeurs et, le cas échéant, leur accorder toutes les ressources
nécessaires (CVS, listes de diffusions...) ?

7ème point : qui gèrera le "layout" et donc le site ? La régénération du
HTML (on est en statique) ? Suivant quelle périodicité ?

8ème point : peut-on prévoir des CSS un peu moins ternes ? Organiser un
concours de CSS ? Faire voter les utilisateurs (Savannah, contrairement
à SourceForge, ne semble pas proposer de "surveys" :-O ) ? Si l'on
venait à proposer des améliorations aux XSL, dans quelle mesure
serait-on liés - moralement - à docbook ? J'entends par là que si l'on
s'astreint à leur faire part de nos avancées, celles-ci seront peut-être
conditionnées par le souci que nous aurons de faire "générique" et -
pourquoi pas ? - de renoncer à des choses qui nous auraient tenu à
coeur.

Voilà pas mal de questions très pratiques en suspens ; les réponses n'en
sont pas forcément complexes mais je pense qu'on ne peut décemment pas
commencer sans elles.

Pendant que j'y suis : sur la racine du CVS des sources
(http://savannah.gnu.org/cgi-bin/viewcvs/sdx/), on a un
répertoire/module "sdx". J'imagine que c'est une fausse manip ?

A bientôt.

--
Pierrick Brihaye
mailto:address@hidden