[sdx-developers] RE : Systeme de documentation

[Martin Sévigny]

Bonjour,

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

Website-full utilise tout Docbook. Website-custom est basé sur
Simplified Docbook. Website.dtd est une version "automatique" obtenue
par l'une ou l'autre des "customization" de Docbook.

J'opterais pour la simplifier, on commence les documents par "article"?

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

Pas que l'on veut, tout de même. Comme toute DTD normalisée, il y a du
générique et du flou, mais tout a une définition...

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

Sgmltag est un inline, les autres sont des blocs (de méméoire). Un bout
de fichier XML sur plusieurs lignes devrait être du programlisting selon
moi. Le literal est plus générique.

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

On peut les construire à mesure. Je ne crois pas que ce soit le plus
critique à ce moment, mais c'est que c'est toujours préférable de partir
du bon côté.

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

Il pourrait y avoir un glossaire, effectivement.

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

Ils doivent être uniques dans une collection. J'aurais tendance à donner
des identifiants alphanumériques significatifs en minuscules. Du genre
tech_intro, peu importe. Mais si vous voulez quelque chose de plus
complexe...

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

J'organiserais les fichiers en dossiers, d'abord, dossiers ayant une
réalité sémantique, grosso modo des sections. Pour le multilinguisme,
j'hésite entre deux hiérarchies ou mélanger les fichiers en les nommant
différemment.

> 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...) ?

Je crois que c'est possible. A voir sur Savannah.

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

Aussi fréquemment que possible. On verra quand on aura de la doc?

> 8ème point : peut-on prévoir des CSS un peu moins ternes ? 

Oui, éventuellement, si ça intéresse quelqu'un de le faire. Je pense que
c'est préférable de documenter d'abord!

> venait à proposer des améliorations aux XSL, dans quelle mesure
> serait-on liés - moralement - à docbook ? 

Tu peux modifier n'importe quoi dans les XSL docbook sans y toucher
comme tel. Tu dois importer (et non inclure) les XSL et tu surcharges ce
que tu n'aimes pas. Je crois que ça devrait être l'approche à utiliser
pour SDX.

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

Je pense que oui. L'idée de faire sdx_v1 et sdx_v2 (pour répondre à
Patrice) est issue du fait que SDX 2 sera une réécriture de SDX 1, pas
une mise à jour. Ma connaissance limitée du CVS me laissait penser qu'il
serait préférable de coder une nouvelle application plutôt que de se
battre avec ces tags plutôt sujets à erreur.

De plus, je veux que les utilsateurs soient conscients que ce sont deux
applications à architecture différentes.

A bientôt,

Martin Sévigny