Re: to pitch or not to...

[Valentin Villenave]

2010/2/22 Pierre RUEL <address@hidden>:

Nous voilà donc avec une question centrale :

> pour moi un manuel se suffit à lui-même, c'est-à-dire qu'il contient sa
> propre introduction, sa préface, son avant-propos et tout ce qu'il y a à
> savoir pour l'intelligence du manuel proprement dit.

L'ancien manuel contenait effectivement ces prolégomènes (que
l'éditeur de la documentation, Graham Percival, qualifierait
volontiers de "fluff", c'est-à-dire une lecture plaisante mais peu
utile).

La nouvelle page de manuels
(http://lilypond.org/doc/v2.13/Documentation/web/manuals) renvoie à
diverses ressources, au premier chef desquelles la fameuse page
"saisie sous forme de texte" dont je vous parlais tantôt.

> permettez-moi de penser que compte tenu du temps que vous avez
> passé à travailler sur le logiciel, sa documentation et son site, vous ne
> pouvez absolument pas en faire une visite "spontanée".

C'est toute la difficulté : vous-même avez également dépassé, il me
semble, le stade de "visiteur naïf". Il n'en demeure pas moins que
(comme la plupart des logiciels, libres ou non), le premier aperçu
qu'ont les nouveau venus est le site Web, bien avant d'ouvrir la
documentation.

> je trouve personnellement
> extrêmement fastidieux que, pour aller d'un point A, l'introduction, au
> point B, le logiciel, il faille ricocher de page en page pour trouver des
> informations qui pourrait parfaitement être exposées de façon discursive

Je comprends votre point de vue. Comme je vous l'expliquais, la
documentation était autrefois structurée d'une façon plus linéaire ;
la raison pour laquelle elle a été réorganisée tourne autour du
postulat suivant :
là où la documentation elle-même est faite pour être compulsée, lue,
relue, en détail, les pages introductives (telles que l'"essai", ou la
page "saisie sous forme de texte") sont formulées de façon plus
attrayante (illustrations en couleurs, etc.) et sont destinées à
n'être lues qu'une seule fois.

À ce titre, nous ne considérons plus ces pages comme faisant partie du
manuel. Un exemple : l'introduction que vous nous avez concoctée se
réfère aux logiciels graphiques existants. Cette information est
parfaitement valable et nécessaire (tout au moins dans un premier
temps), en ce qu'elle explique aux utilisateurs habitués à un certain
paradigme (souris/écran) qu'ils doivent abandonner leurs repères
habituels.
La documentation en elle-même, en revanche, ne s'adresse pas
nécessairement aux utilisateurs habitués à ce paradigme, mais bien à
*tous* les utilisateurs, d'où qu'ils viennent et quel que soit leur
passé !

De même pour le glossaire ou l'essai, dont la lecture n'est pas vitale
pour l'utilisation de LilyPond : il semble logique qu'ils fassent
l'objet de documents séparés.

> D'ailleurs pourquoi y a-t-il 2 manuels ? Lilypond étant un
> logiciel de notation, le manuel Lilypond *est* le manuel de notation. J'ai
> d'ailleurs perdu pas mal de temps à retrouver telle ou telle indication car
> je n'avais pas noté si elle provenait du manuel d'initiation (d'initiation à
> quoi, sinon à la notation ?) ou du manuel de notation.

Puisque vous venez d'une culture classique, je pense que la notion de
"digeste" ne vous sera pas étrangère...
Le manuel d'initiation est destiné à être lu entièrement, de façon
linéaire. À ce titre il reprend des notions importantes du manuel de
notation, et les présente d'une façon (censément) adaptée aux
débutants, "discursive" comme vous le disiez ci-dessus, et
progressive.
Le manuel de notation, pour sa part, est "la" référence exhaustive.
L'on ne s'en sert que pour chercher tel ou tel point bien précis, dès
que les notions (relativement) simples apprises dans le manuel
d'initiation ne suffisent plus.

> C'est un point sur lequel je suis en complet désaccord, comme je l'ai déjà
> dit. D'ailleurs après avoir lu le texte intitulé "essai" et ses
> considération esthétiques un rien maximalistes, je n'ai pas vu l'intérêt de
> lire la totalité de la prose des auteurs du logiciel.

Je vous laisse très volontiers ce point de vue, en ce qui me concerne
c'est précisément ce texte qui a achevé de me convaincre d'adopter
LilyPond. Au demeurant, ledit "essai" n'est que lointainement dérivé
de la "prose" des deux auteurs d'origine, et vient de surcroît d'être
(lui aussi) entièrement réécrit par un simple contributeur qui
n'appartient pas à l'équipe de développement.
Un logiciel Libre n'est pas un _produit_ achevé, mais un _projet_
collectif en perpétuelle évolution (dans le bon sens, espérons-le), et
à ce titre il n'y a pas de différence fondamentale entre un
utilisateur et un contributeur -- notre discussion en étant un bon
exemple, puisque certaines de vos remarques (par exemple l'avancement
des traductions) rejoignent les préoccupations de la communauté.

Cordialement,
V. Villenave.