sdx-developers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [sdx-developers] Documentation


From: Pierrick Brihaye
Subject: Re: [sdx-developers] Documentation
Date: Tue, 24 Sep 2002 15:50:44 +0200
User-agent: Mozilla/5.0 (Windows; U; Win98; fr-FR; rv:1.0.1) Gecko/20020823 Netscape/7.0

Salut,

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.

Tout cela est compréhensible... et compris !

mais j'ai absoluiment besoin de relecteurs, je ne connais pas
encore bien l'exercice.

Je veux bien m'y mettre... l'apsect "communication" me paraît très important (ne serait-ce que pour toucher mon salaire à la fin du mois).

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

OK.

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

Oui. C'est mieux à mon avis.

J'aurais tendance à considérer le lecteur ainsi :
    - il comprend le principe général de Cocoon

Mmmh. Je ne suis pas trop d'accord. Ici, personne ne sait que SDX tourne sur Cocoon :-)

    - il sait retirer son info d'une doc en anglais

Pour Cocoon, il y a du boulot ! J'ai vraiment un mal fou à m'y mettre parce que la doc semble d'adresser à un happy few... qui connait déjà Cocoon. Mais bon, je reçois le bouquin ces jours-ci : ça devrait aller mieux bientôt.

    - une appli SDX peut être sa première occasion de développer sous cocoon

Je comprends, mais cet argument risque d'être assez contre-productif. Les gens veulent une appli documentaire : point !

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

Pour ça, OK.

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.

Pour SDX, je coince : Win 95, Win 98, Win NT sont mes références (pauvre de moi !). Pour "API", le tiret me va, même si là encore, ça n'est pas dans mes habitudes : SDK Java, NNTP server, XSL FO... qui s'opposent à XML-Schema.

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

Pourquoi pas ?

C'est un peu lourd, mais d'une grande aide pour le lecteur
connecté.

Oui.

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.

Hé hé, le DocBook simplifié, c'est la tarte à la crème : tout le monde en veut, mais il n'y en a pas :-)

A+

--
Pierrick Brihaye, informaticien
Service régional de l'Inventaire
DRAC Bretagne
mailto:address@hidden





reply via email to

[Prev in Thread] Current Thread [Next in Thread]