Réécriture

Jeudi 25 août 2005 22:53 - Divers

Ça commence par quelques phrases sur mon style d'écriture, je ne les écris pas, évitant ainsi les qualificatifs qui seraient terreau à des « ah non, je ne voyais pas ça comme ça » ou des « tu rêves, cher ami », ou pas. Dans ces phrases, ce style est placé par rapport au style de documents techniques, carrés, professionnels, jouons ici des italiques.

J'ai écrit un compte-rendu, un rapport, une présentation, une documentation, peu importe le terme, le public était restreint, il n'avait rien demandé. Deux semaines plus tard, il faudrait publier ça. Une vraie présentation, une vraie documentation, toujours les mêmes termes, mais un public dont la vision d'un document professionnel est, opinion perso, montrez-moi le contraire, étroite.

Réécriture totale ou élagage du superflu littéraire ?

Je tâche l'élagage.

On offre une ressource, c'est une disco:ResourceOffering, ça n'a pas changé, s'y retrouvent quantités d'informations: le type de service offert (lasso.PP_HREF, c-à-d Personal Profile), le provider id, l'URL d'accès pour les messages SOAP et le mécanisme de sécurité à utiliser (ici rien du tout vu que rien n'est encore implémenté). Parce qu'on le vaut bien, on ajoute aussi quelques mots sur le service.

Bon, il y aurait beaucoup à redire, je saute l'analyse et tente l'écriture.

Comme expliqué plus haut, le serveur voulant annoncer une offre de service le fait au travers d'un message disco:ResourceOffering. Dans ce message doivent figurer plusieurs informations: le type de service offert (par exemple lasso.PP_HREF pour le Personal Profile), l'identifiant du serveur (élément providerId), le mécanisme de sécurité à utiliser (celui-ci peut être ignoré pour les premiers développements), l'URL où devront être postés les messages SOAP ainsi qu'une description du service.

Je ne commente pas, on notera le professionnalisme dans la désignation du mécanisme de sécurité: d'un système pas implémenté on en fait quelque chose dont on soulage le lecteur. Un peu de cynisme dans cette vision de la profession, oui, pas une raison pour s'y attarder, au tour du paragraphe suivant:

Après ça devient sérieux, il s'agit de lier pour la vie cette offre à une ressource, identifiée par un resource id, il a été généré un peu plus haut, c'est aussi un des attributs de l'objet user.

« Ça devient sérieux », « lier pour la vie », les appendices à sectionner sont somme toute faciles à repérer, hop:

L'action suivante consiste à lier l'offre de service à une ressource, qui sera identifiée par un élément resourceId. Celui-ci doit être généré par le serveur selon les règles précisées dans le chapitre 4, section 2, des spécifications. Il doit faire partie de l'objet identifiant l'utilisateur et stocké avec celui-ci.

Je fatigue, je masque cela en tapant une référence vers document que le lecteur aura alors à chercher, lire, etc. ce qui aura le mérite de lui faire perdre son fil de lecture et de ne pas se rendre compte que tout ce qui est écrit est fort décousu.

Je termine sur le paragraphe qui suit, parce qu'il est symptomatique:

Voilà, il suffit d'en générer un message et de l'envoyer ça au service "disco" (my bond with you and your planet) (en fait l'IdP).

Quelle nécessité à cette parenthèse ? Qui aura les références permettant de dépasser le « euh » ? Même dans le premier cercle de lecteur, il y en avait au mieux un seul, et je ne suis même pas sûr. À éliminer.

Il faut alors générer un message SOAP de ces informations et communiquer celui-ci au service discovery (qui dans le cas présent est le fournisseur d'identités).

C'est un exemple de réécriture. Je n'en fais pas la relecture, de toute façon demain je ferai ça différemment.