[sdx-developers] Documentation

[Frédéric Glorieux]

> introduction/serveur.xml :
>
> >Pour que SDX puisse offrir ses services d'indexation, de recherche et
> d'affichage de documents XML, un serveur Web, un moteur de servlets et SDX
> doivent être en marche et correctement configurés >pour être prêts à
servir
> les requêtes
>
> La phrase est lourde !

C'est logique de commencer à lire par le début, mais c'est aussi les
premières pages écrites, et donc les moins affinées. Martin a jeté des
phrases de premier jet, afin surtout de définir les parties et les contenus.
Je repasse en ce moment page à page, je crois avoir fini la migration, je
renseigne l'API, mais je ne suis pas encore trop passé par l'introduction.
D'un point de vue communication, ce sont certainement des pages très
importantes, qui pourront être lues par des personnes ne connaissant pas
SDX, voire, des décideurs qui ne sont pas techniciens. Je promet d'y mettre
une couche, mais j'ai absoluiment besoin de relecteurs, je ne connais pas
encore bien l'exercice.

>
> >L'adresse du serveur
>
> Ici, j'ai du mal à comprendre : on accède au serveur par son IP ? ou bien
> par un nom d'hôte (qui peut d'ailleurs être une IP) ? Cet aspect est
> important tant que la majorité des particuliers n'auront pas d'IP fixes.

Il s'agit ici d'un "commentaire de texte" de sdx.xconf, dans un lieu ou l'on
ne doit pas citer le source. L'exercice n'est pas aisé, les concepts
demandent à être mieux arrêtés pour parler plus clairement au profane. Or
l'emploi de ce fichier est en évolution (communication entre les serveurs
pour partager des bases ...).

> introduction/bases.xml :
>
> >(même si elle est toujours vide)
>
> Même si j'ai une petite idée de ce qui se cache derrière un serveur
n'ayant
> qu'une base vide, pouvez-vous expliquer ?

> introduction/entrepots.xml :
>
> >certains types d'entrepôts devront être utilisés
>
> On peut les préciser ?

Commentaire de application.xconf ; nous savons maintenant bien de quoi nous
parlons ici, sera réécrit.

>
> migration/configuration.xml :
>
> >En SDX 2, cet élément supérieur devient plutôt quelque chose comme :
>
> Ne sommes-nous pas en sciences exactes ?

Qui empêche un auteur d'application d'ajouter ses propres attributs ? La
tournure pourrait être plus précise, du genre :
L'élément racine est ... et devra au moins porter les attributs ...

>
> migration/sitemap.xml :
>
> Préciser que les changements ont été conditionnés par le passage à Cocoon
2
> ?

Plus globalement en divers autres points de la doc, il s'agit de mesurer ce
qu'il faut dire de Cocoon-2 pour faire une bonne appli SDX, sans pour autant
faire le travail de cocoon (doc parcellaire et non traduite en français).
J'aurais tendance à considérer le lecteur ainsi :
    - il comprend le principe général de Cocoon
    - il sait retirer son info d'une doc en anglais
    - une appli SDX peut être sa première occasion de développer sous cocoon
Donc, définir les concepts sans pour autant les développer, donner des
exemples de codes sans trop de commentaires, mais toujours appuyer par des
liens vers http://xml.apche.org/cocoon


> Sinon :
>
> "SDX-2" ou "SDX 2" ? Idem pour SDX-1 et Cocoon-2...
> quel tag Docbook utiliser sour marquer les noms de logiciels ? Cocoon,
> MySQL, Tomcat... SDX ?

Ayant introduit le tiret (de même que dans API-URL, API-SDX ...) je serais
enclin à unifier ces désignations comme des mots composés, mais si quelqu'un
a un argument contre, je me rétracte et corrige immédiatement. Concernant
les tags Docbook, je ne sais pas si "logiciel" est la meilleur unité pour
identifier des projets libres. Ce ne sont ni des <trademark/>, ni des
<acronym/>, pour ma part je proposerais des liens URL <ulink/>
systématiques. C'est un peu lourd, mais d'une grande aide pour le lecteur
connecté. Cela permet, selon le contexte, de spécifier des pages précises :
    > XML-Schema est une norme <ulink
url="http://www.w3.org/XML/Schema";>W3C</ulink>
On peut y ajouter un marqueur par l'attribut role, valeurs à définir (

Par ailleurs, il serait bon d'arrêter une structure de page plus restrictive
que la DTD. Je pense à ceci
<webpage>
    <head>...
    <abstract>...
    <section> x n
    <appendix><title>Conclusion</title>...

La question est de savoir si introduction et conclusion font partie des
sections ou pas. Je pense que non, mais chacun ayant ses goûts dans ces
affaires de style, je me rendrais à l'avis de la majorité. Un élément
<abstract/> me semble très utile en début de page, par contre, forcer à une
conclusion, et en plus la considérer comme une annexe, je reconnais que
c'est largement discutable, mais je ne vois que cette solution pour
s'assurer d'un paragraphe en fin de page qui ne soit pas dans la
numérotation des sections.