Documentation mal écrite

Vous avez une idée pour améliorer ou modifier PureBasic ? N'hésitez pas à la proposer.
Bougalou
Messages : 6
Inscription : lun. 24/juil./2006 17:32

Documentation mal écrite

Message par Bougalou »

Depuis peu, je découvre PureBasic avec grand plaisir. J'ai été séduit par sa qualité, sa puissance et sa fidélité aux formes et structures originelles du langage. À programmer en Purebasic, j'ai retrouvé le bonheur que j'avais -- il y a trop longtemps -- à utiliser GFABasic sur mon Atari 1040ST (sans disque dur!). En Purebasic, Basic redevient alerte, facile, amusant et rapide à mettre en oeuvre. Bravo.

Par contre, la documentation surprend. Mal. Elle laisse, à mon avis, beaucoup à désirer. Son écriture et sa présentation ne font pas très sérieux. Le texte du fichier d'aide contient beaucoup trop de fautes d'orthographe et d'erreurs de grammaire pour être acceptable. Il n'est simplement pas à la hauteur de votre superbe produit.

Pour dire les choses très clairement: Je ne parle pas du tout ici du contenu; ceux qui ont programmé le compilateur, l'IDE et les bibliothéques d'accompagnement sont mieux à même que n'importe qui d'évaluer la justesse et la précision de la documentation. Je ne parle que de la forme. Le fichier d'aide fourni avec le logiciel met sérieusement à mal le français, au détriment de l'image de PureBasic.

J'ai toujours eu du mal à comprendre que des gens capables de se plier aux exigences de syntaxe strictes et à la grammaire inflexible d'un langage de programmation soient incapables de manipuler correctement la syntaxe et la grammaire de leur langue naturelle. Cela dépasse l'entendement. En plus, considérant le grand nombre de gens qui fréquentent ce forum, il est plutôt surprenant que vous n'ayez pas réussi à dénicher un réviseur capable de donner à ce texte une qualité minimale plus acceptable.

Un client ou un utilisateur potentiel forme souvent sa première impression d'un logiciel -- à plus forte raison d'un langage de programmation -- à la lecture de la documentation. Si celle-ci paraît amateur et mal ficelée, le lecteur pourra en arriver, à juste titre, à craindre que la qualité du compilateur et des outils de développement qui l'accompagnent soient à l'avenant. S'il y a une leçon que tout le monde devrait avoir retenue des succès de Microsoft, c'est bien celle-là!

L'enthousiasme et l'intérêt des participants du forum à l'égard de "leur" langage de programmation est manifeste. Il n'est donc pas excessif de supposer que la majorité d'entre eux aimeraient bien que croisse cet intérêt. Alors, pour que PureBasic progresse et soit pris au sérieux, il me semble que vous devriez commencer par faire l'effort de produire une documentation davantage à la hauteur du produit que vous avez si brillamment développé et assemblé (calembour heureux et intentionnel :lol: ).


Un lecteur-programmeur attentif


PS: l'essentiel de ce que je viens d'écrire s'applique tout autant à la documentation en anglais. Je ne l'ai pas lue avec le même soin que la documentation en français, mais de grands bouts de ce texte m'ont paru davantage rédigés en pidgin English qu'en anglais d'un standard attendu pour un produit sérieux. Pas étonnant que certains ne se rendent pas jusqu'à essayer le logiciel.
Backup
Messages : 14526
Inscription : lun. 26/avr./2004 0:40

Message par Backup »

Actuellement la Doc en Français est corrigé et completé par Comtois
en autre, rien de t'empeche de lui donner un coup de main :D
comtois
Messages : 5186
Inscription : mer. 21/janv./2004 17:48
Contact :

Message par comtois »

Il y a un post pour en parler ici :
http://purebasic.forum-gratuit.com/viewtopic.php?t=4789

Tes remarques seront les bienvenues.
http://purebasic.developpez.com/
Je ne réponds à aucune question technique en PV, utilisez le forum, il est fait pour ça, et la réponse peut profiter à tous.
Bougalou
Messages : 6
Inscription : lun. 24/juil./2006 17:32

Message par Bougalou »

He ben, dites donc, les choses ne traînent pas chez vous... Sitôt écrit, sitôt répondu. 8O Y a vraiment des gens qui lisent tout et n'importe quoi! :D
Dobro a écrit : [...] rien de t'empeche de lui donner un coup de main :D
Rien ne m'empêche, en effet, et ça me fera même plaisir de réviser la documentation...
(1) si on me le demande
(2) si on m'en donne l'occasion et la possibilité.

Mais mon expérience en la matière me laisse dubitatif. J'ai en effet constaté que, le plus souvent, les susceptibilités des gens finissent par avoir raison des meilleures intentions...

Quioi qu'il en soit, l'offre est faite. Si elle intéresse quelqu'un, qu'on me le laisse savoir.
Bougalou
Messages : 6
Inscription : lun. 24/juil./2006 17:32

Message par Bougalou »

comtois a écrit :Il y a un post pour en parler ici :
http://purebasic.forum-gratuit.com/viewtopic.php?t=4789

Tes remarques seront les bienvenues.
Merci.

Je suis déjà allé faire un tour de ce coté-là, mais, à lire en diagonale, j'ai cru comprendre que les efforts, nombreux, portent d'abord et surtout sur le contenu de la documentation. Or moi, je ne voulais parler que de la forme.

J'ai téléchargé la dernière mise à jour du fichier d'aide (celle du 15 juillet) et j'ai constaté avec plaisir que le fichier a beaucoup évolué et de manière très positive. Vous êtes, à n'en pas douter, dans la bonne voie. Bravo.

Mais mon offre demeure quand même: si vous voulez un coup de main pour la révision de l'ensemble, je suis prêt à aider.

"Mais pour corriger quoi ?" vous demandez-vous peut-être. Bien, par exemple...
(1) Vous dites bien "bibliothèques" en parlant des DLL et des compilations de code PureBasic pré-assemblé, mais, oupse, le mot 'librairies" des versions précédentes est resté collé à maints endroits dans la page "Historique", tout comme dans quelques autres pages.
(2) En page "DrawingMode()", il est écrit que la fonction "change la mode d'affichage".
(3) Dans la colonne de gauche, à la rubrique "Manuel", les 12 premiers titres sont restés en anglais.
(4) Dans la page "Débuter avec l'IDE", il est écrit "leurs compilation", "un raccourcis des fonctions".
(5) Dans la page des remerciements, vous écrivez "Tous les utilisateurs enregistrés: Pour supporter activement le développement ". Désolé, mais cette formulation calquée directement de l'anglais n'est pas française. Vous pourriez dire "Aux utilisateurs enregistrés: Pour leur appui fidèle et enthousiaste à PureBasic et à son développement.", ce qui dirait la même chose, mais en français et en mieux!
(6) Il est dit un peu partout qu'une fonction "retourne" une valeur. Or, en français, une fonction renvoie une valeur, en dépit du fait que nos amis anglophones la "return" ! La seule chose qu'on retourne en français, ce sont les crêpes...

... et je pourrais continuer ainsi encore un certain temps, même si -- je le répète et j'insiste -- les progrès entre cette version du 15.07 et celle installée par le programme d'installation me paraissent tout à fait remarquables et fort appréciables.

Bref, pour épingler ce genre de coquilles, d'oublis ou d'erreurs, et pour corriger les gaucheries de style et de syntaxe, il faut un réviseur à l'oeil de lynx et à la plume alerte, qui sache les repérer pour les corriger. Je vous propose mes services.

Voilà. Bonne soirée.
Dernière modification par Bougalou le mar. 25/juil./2006 16:39, modifié 2 fois.
Backup
Messages : 14526
Inscription : lun. 26/avr./2004 0:40

Message par Backup »

Mais c'est tres bien tout ça :D
comtois
Messages : 5186
Inscription : mer. 21/janv./2004 17:48
Contact :

Message par comtois »

(1) Vous dites bien "bibliothèques" en parlant des DLL et des compilations de code PureBasic pré-assemblé, mais, oupse, le mot 'librairies" des versions précédentes est resté collé à maints endroits dans la page "Historique", tout comme dans quelques autres pages.
RegisLG avait proposé de corriger la page Historique, à l'époque il y avait plus urgent à faire, mettre la doc française au niveau de la doc anglaise, donc on a fait l'impasse sur cette page, maintenant on peut faire une petite passe. Si tu connais les autres pages, merci de les indiquer.
Sinon je ferai une petite recherche.

(2) En page "DrawingMode()", il est écrit que la fonction "change la mode d'affichage".
C'est corrigé.
(3) Dans la colonne de gauche, à la rubrique "Manuel", les 12 premiers titres sont restés en anglais.
RegisLG et Denis et peut-être d'autres l'ont déjà signalé, Il n'y a que Fred qui peut faire la modif et pour l'instant il est très pris pour la v4 Linux :)
(4) Dans la page "Débuter avec l'IDE", il est écrit "leurs compilation", "un raccourcis des fonctions".
là aussi RegisLG avait commencé à faire des corrections, ce qui me gêne avec les pages de l'IDE, c'est qu'avant de s'attacher à la forme il faudrait en finir avec le fond. ça fait plusieurs fois qu'on le corrige.

Dans l'IDE, les textes débordent des boutons, je pense qu'il faudrait d'abord s'attacher à réduire les textes du fichier ini de l'IDE et ensuite reprendre la doc , les images , de façon à rester cohérent et dans le même temps faire une lecture approfondie.

Je ne sais pas si quelqu'un souhaite se charger de ça ?
ou alors je peux considérer que l'IDE est parfait , et je peux commencer à reprendre la doc avec les textes de l'IDE ?

(5) Dans la page des remerciements, vous écrivez "Tous les utilisateurs enregistrés: Pour supporter activement le développement ". Désolé, mais cette formulation calquée directement de l'anglais n'est pas française. Vous pourriez dire "Aux utilisateurs enregistrés: Pour leur appui fidèle et enthousiaste à PureBasic et à son développement.", ce qui dirait la même chose, mais en français et en mieux!
C'est vrai que le plus souvent les phrases sont calquées de l'anglais, c'est lié à une traduction mot pour mot pas toujours très heureuse, mais personne ne s'était plaint jusqu'à présent :)

Je ferai la correction que tu proposes.

(6) Il est dit un peu partout qu'une fonction "retourne" une valeur. Or, en français, une fonction renvoie une valeur, en dépit du fait que nos amis anglophones la "return" ! La seule chose qu'on retourne en français, ce sont les crêpes...
On peut retourner sur ses pas, retourner un compliment , et bien d'autres choses encore , mais je veux bien admettre que renvoyer semble plus approprié. Je ferai une recherche pour changer retourne par renvoie.



Pour faire les corrections il faut un accès au cvs en éciture, pour l'instant je suis le seul à l'avoir.
Tu peux toujours en faire la demande à Fred, c'est lui qui décide.

Sinon tu peux accéder au cvs en lecture, ça te permet de récupérer toute la doc,de faire les modifs, et ensuite tu m'envoies les fichiers que je les recopie pour les valider.
Si c'est juste pour changer un article la en le , tu peux me laisser un message en m'indiquant dans quelle fonction et je ferai la modif.
http://purebasic.developpez.com/
Je ne réponds à aucune question technique en PV, utilisez le forum, il est fait pour ça, et la réponse peut profiter à tous.
Frenchy Pilou
Messages : 2194
Inscription : jeu. 27/janv./2005 19:07

Message par Frenchy Pilou »

Quelqu'un qui a taté du GFA, et qui plus est, semble très à cheval sur la langue, semble être la personne rêvée pour cette fameuse documentation PureBasicienne (néologisme, j'en ai bien peur) :D
En attendant, ces remarques un tantinet acidulées, sont un régal pour nos pauvres yeux :lol:
Est beau ce qui plaît sans concept :)
Speedy Galerie
comtois
Messages : 5186
Inscription : mer. 21/janv./2004 17:48
Contact :

Message par comtois »

j'ai mis en ligne un nouveau fichier pour prendre en compte tes remarques

C'est le premier lien dans ma signature pour télécharger, et voir ici pour les détails :

http://purebasic.forum-gratuit.com/view ... 2753#52753
http://purebasic.developpez.com/
Je ne réponds à aucune question technique en PV, utilisez le forum, il est fait pour ça, et la réponse peut profiter à tous.
Bougalou
Messages : 6
Inscription : lun. 24/juil./2006 17:32

Message par Bougalou »

-doublon supprimé-
Dernière modification par Bougalou le mar. 25/juil./2006 21:32, modifié 1 fois.
Bougalou
Messages : 6
Inscription : lun. 24/juil./2006 17:32

Message par Bougalou »

En réponse à Comtois:
Tu sais, tu n'es pas obligé de répondre point par point à chacun des exemples que j'ai soulevés. Ce ne sont pas des accusations qu'il te faut réfuter à la pièce. J'essayais simplement d'illustrer ce qui, au-delà du contenu, reste encore à faire pour raffiner la formulation de la documentation et donner un peu plus de vernis professionnel à l'ensemble. Il n'y avait pas là-dedans de reproche implicite, ni de connotations négatives. Alors une réplique détaillée, avec justification et rappel de l'apport de chacun à l'appui, me paraît déplacée, inappropriée et à côté de la plaque. En bref, je m'en tape.

Le type de révision que j'estime nécessaire ne peut ni ne doit se faire en comité (formel ou informel, comme par exemple en échangeant des messages ponctuels sur le forum!); elle exige la main-mise d'un réviseur qui sait écrire(i.e grammaire, orthographe ET style). Si mon intervention t'agace, comme tes réponses le laissent soupçonner, et si tu estimes que je viens piétiner tes plate-bandes avec mes gros sabots, mille pardons. Puisque tu sembles être le chef d'orchestre de la documentation, tu n'as qu'à répondre par la négative à mon offre et me refuser le rôle de premier violon que je prétendais postuler.

Après tout, comme tu le dis si bien, personne ne s'était encore jamais plaint (avant moi, il va sans dire! ce qui représente une contradiction de facto, mais on en débattra une autre fois.) des traductions bancales et du franglais trop récurrent qui viennent déparer la documentation. Si tout le monde est tant tellement content et satisfait, pourquoi se fatiguer? Mais je t'avoue me retrouver quelque peu pantois devant ton argumentation: jamais encore je n'avais connu de situation où il fallait attendre que les gens se plaignent pour s'activer à rédiger un texte en vrai français. Pauvre de moi, j'ignorais même que ce pouvait être un critère... Comme quoi il n'y a en effet pas d'âge pour apprendre.

Non, je ne vais pas communiquer avec Fred. Si ceux qui, comme toi, sont depuis belle lurette en charge de la rédaction ne le font pas, ça n'arrivera pas. Je me vois mal proposant à un gars que je ne connais pas de me donner carte blanche dans la révision de la documentation qui doit accompaner son bébé. Voyons voir: Comtois: 2355 messages; Dobro: 3400 messages; Frenchy Pilou: 679 messages (un p'tit nouveau?); Bougalou: 3 messages. Hum... Je ne fais décidément pas le poids, et la crédibilité est encore tout à construire. En plus si je suis incapable de convaincre le plongeur en chef, pourquoi m'acharner à reprendre le débat avec le grand cuisinier lui-même ? Nah.....

Au sujet du verbe renvoyer: s'il doit doit remplacer retourner pour décrire l'effet d'une fonction, ce n'est pas parce qu'il est "plus approprié" ou parce que je le préfére. C'est simplement qu'il est le seul qui convienne, puisqu'il décrit à la lettre l'action réalisée lors d'un retour d'appel de fonction, et surtout parce qu'il fait partie depuis très longtemps de la terminologie normalisée de l'informatique en français. PureBasic est un trop bon langage informatique pour se satisfaire d'une documentation écrite à peu près. Pour s'inscrire dans la lignée des développements positifs en programmation, PureBasic doit en adopter la nomenclature. Ça n'a rien à voir avec ma petite personne, ni avec mes préférences personnelles, ni avec les tiennes d'ailleurs. C'est une question à la fois de tradition établie, et de génie de la langue.

En terminant, un grand merci pour le cours aussi bref que clair et précis sur les multiples usages du mot retourner en français. Je me disais bien aussi qu'on ne pouvait pas ne retourner que des crêpes en français... J'ai bien compris. Plus de blagues douteuses de ma part. Je me le tiens pour dit.

Désolé pour le dérangement.

PS: le petit rigolo qui a rédigé les README en anglais que l'on retrouve dans plusieurs sous-dossiers de PureBasic a-t-il jamais complété son primaire? Les textes de ces fichiers sont une vraie honte et une insulte à la langue anglaise.
comtois
Messages : 5186
Inscription : mer. 21/janv./2004 17:48
Contact :

Message par comtois »

Je n'ai pas pris tes remarques comme un reproche et je ne tentais pas de me justifier en quoi que ce soit. Je voulais seulement de te donner des indications sur l'avancement et pourquoi certaines choses n'étaient pas encore corrigées.
Et si j'ai cité d'autres noms , c'était pour bien montrer que c'était un travail collectif, et pas seulement le mien.

Je ne suis pas responsable de cette doc, je tentais simplement de l'améliorer dans la mesure de mes faibles moyens. Je ne prétends pas non plus être le plus apte à le faire aussi je te cède volontiers la place.

Le plongeur en chef jette son tablier ! il a beaucoup mieux à faire !
http://purebasic.developpez.com/
Je ne réponds à aucune question technique en PV, utilisez le forum, il est fait pour ça, et la réponse peut profiter à tous.
Avatar de l’utilisateur
djes
Messages : 4252
Inscription : ven. 11/févr./2005 17:34
Localisation : Arras, France

Message par djes »

Bougalou> Du calme, Comtois a seulement essayé de répondre à ton message, comme toi tu l'aurais fait à sa place. On dirait que tu n'as pas l'habitude des forums. Le fait qu'il ait travaillé ainsi prouve qu'il a apprécié tes remarques.

Il faut quand même que tu saches aussi que Purebasic est un langage de passionnés. Depuis peu, son prix a augmenté, mais tu peux être sûr qu'avant, le bénéfice dégagé ne permettait pas d'embaucher quelqu'un pour réaliser une doc digne de ce nom, autant dans la langue de Shakespeare que dans la nôtre, et chacun contribuait à l'améliorer bénévolement selon ses moyens. Maintenant, cette situation va peut-être changer, pour le meilleur ou pour le pire, nous jugerons alors.
Avatar de l’utilisateur
Jacobus
Messages : 1559
Inscription : mar. 06/avr./2004 10:35
Contact :

Message par Jacobus »

Comtois, tu as toute notre sympathie et notre reconnaissance pour le travail que tu fais... et perso je préfère parler au cocher qu'à la mouche qui lui tourne autour.
De plus, t'es pas aux pièces ni à la botte, alors...
@+
Quand tous les glands seront tombés, les feuilles dispersées, la vigueur retombée... Dans la morne solitude, ancré au coeur de ses racines, c'est de sa force maturité qu'il renaîtra en pleine magnificence...Jacobus.
Backup
Messages : 14526
Inscription : lun. 26/avr./2004 0:40

Message par Backup »

oui c'est vrais avant de prejuger de l'action de quelqu'un sur un forum comme celui ci,
la premiere chose a faire est de se tenir informé des US et Coutumes du forums or ici personne n'est la pour donner des leçons aux autres
encore que Comtois pourrai te donner des leçons d'informatique sans probleme , car je suppose qu'un mec qui a passé sa vie dans les Dicos n'as pas eu le temps d'aprendre grands chose en prog :D

meme les academiciens debattent pendant plusieurs mois , sur la definition exacte d'un terme, alors ...

tant qu'a choisir, entre un obsedé de la grammaire, et Comtois qui fait de son mieux, pour nous faire une Doc plus que correcte , je choisi d'office Comtois :D

personnellement je te retient pas Bougalou , adieu !! :lol:

l'autre il debarque, il nous sort que la doc est naze
que les connards qui essaie, de l'ammelioré ferai bien d'aller s'pieuté
et ben bouge de la , nez de boeuf !! :lol:
Répondre