What is it like to write a technical book?

Comme vous le savez probablement, j'ai récemment fini d'écrire un livre avec quelques co-auteurs. J'ai pris des des notes tout au long de ce travail et je voulais vous décrire le processus pour ceux qui pensent également à écrire un livre.

Je pense qu'il est important d'être objectif; mon propos ici est d'aider de futurs auteurs à découvrir ce à quoi cela peut ressembler, et tout n'est pas fabuleux. J'espère que je n'aurai l'air d'être rancunier envers personne, ou d'essayer de rabaisser des gens. J'ai beaucoup à dire sur ce qui s'est bien passé et mal passé, et comment cela à aider ou entraver le processus.

Excusez l'aspect décousu de cet article. J'aurai aimé mieux l'écrire, mais il y a beaucoup à dire et il faut beaucoup de travail pour écrire un aussi long article de façon structurée.

Peter Zaitsev m'a contacté il y a environ un an et m'a demandé si j'aimerai l'aider à écrire un livre. Dans les premiers temps, l'idée était que j'écrirai quelques appendices et aider à transformer les écrits de Peter et Vadim en de la matière de qualité digne d'un livre; je devais être une sorte d'éditeur technique idéalisé. A cette époque, je ne savais pas qui ce devait être, mais je savais qu'il devait y avoir un quatrième auteur.

Quand Peter m'a contacté, j'ai posé des questions sur la planning, la structure du livre, et ce qui était déjà réalisé. A ce moment-là, le canevas était très vague : seule les chapitres et les titres, avec une phrase ou deux pour expliquer le plan à quelques endroits. Le plan était en partie calqué sur le plan de la première édition, et les chapitres sur les benchmarks, les optimisations, l'indexation et les optimisations des requêtes étaient partiellement écrits.

Le planning avait à vrai dire déjà dérapé, car le livre était supposé être revu techniquement en juin 2007. La proposition était de revoir le planning pour que tout aille en revue technique en octobre 2007. Je ne sais pas quand Peter a réellement commencé à écrire son livre; Andy Oram a passé des années à chercher des auteurs pour la seconde édition, et je pense que Peter avait commencé quelque temps avant que j'embarque dans le navire. Il a ensuite ajouté Vadim et Arjen, mais il était clair qu'il était impossible de réussir à tenir le planning originel.

J'ai demandé à l'éditeur de m'envoyer le contrat, et j'y ai jeté un coup d'oeil. Il était plutôt vague. Les responsabilités, et les étapes pour la réalisation n'étaient pas définis. J'ai demandé à un de mes amis qui avait écrit un livre pour Apress de l'étudier pour moi. Je lui ai demandé à quoi ressemblait le processus. Il m'a décrit un processus qui était très précisément défini; son contrat détaillait quelles étaient ses responsabilités et quelles devaint être les étapes pour publier le livre, qui devait réaliser chaque étape, et quand elles devaient intervenir. S'il ne réalisait pas ses chapitres, il n'était pas responsable pour ceux de son co-auteur. Le contrat de O'Reilly, à l'opposé, était totalement vague. J'ai tourné la question dans ma tête, décidé que le planning proposé était fantaisiste, et décidé de me lancer dans ce projet de livre, mauvais contrat ou pas.

J'ai négocié pour être un auteur complet, plutôt que d'être uniquement mentionné dans les crédits comme proposé au départ par l'équipe de O'Reilly, qui pensait que je ne ferai pas beaucoup de travail. Et j'ai jugé que réaliser ce travail allait me prendre beaucoup de temps. J'ai parlé à mon chef à Rimm-Kaufman Group, et il m'a totalement soutenu pour que je puisse réduire mon temps de travail. Je suis retourné à O'Reilly et je leur ai demandé d'avoir plus d'avance sur les ventes pour me permettre de couvrir ma perte de revenu due à mon travail à mi-temps, et cela a été accepté. J'ai signé le contrat et commencé à travailler. En fait, j'ai probablement d'abord commencé à travailler.

L'industrie des publications techniques travaille probablement de différentes façons, et je ne suis pas expert, mais ce qui m'a le plus surpris était que dans le monde technique, en général, vous n'écrivez pas un livre, puis seulement, vous cherchez un éditeur qui l'imprimera. Cela fonctionne dans l'autre sens. En général, ils font une étude de marché, décident que vous avez besoin d'un livre sur un sujet, et commencent à chercher des gens qui seraient compétents pour l'écrire. Spécialement pour une seconde édition lorsque les auteurs de la première édition ne sont plus intéressés à s'y impliquer, j'imagine que cela doit être un défi.

Le processus

Le processus pour réussir à faire imprimer un livre n'est pas aussi facile que juste l'écrire et l'expédier. Nous avons rédigé une première version, puis l'avons envoyé à l'éditeur, faite passée entre nous, rédigé un nouveau brouillon, ré-édité, ad nauseum. Puis il a dû passer par la revue technique, et nous avons reçu des commentaires et des révisions à faire; il fallut donc encore une fois revoir et éditer; encore de l'écriture, et cela continua encore et encore. Au bout du compte, le livre a réussi à obtenir l'approbation éditoriale finale, et est enfin "parti en production". Si vous pensiez que c'était la fin du travail, ha ha, c'était encore loin d'être terminé. Il y eut encore un réviseur de production, un éditeur de production, un artiste professionnel, de la relecture, du contrôle de qualité, encore de la relecture, la création d'un index, le contrôle de qualité final, et enfin il peut partir à l'imprimerie. Chacune de ces étapes a représenté beaucoup de travail pour moi.

Collaboration et Outils

Nous étions géographiquement assez dispersés, de la Californie à Londres, l'Ukraine, la Virginie et l'Australie. La collaboration a été probablement ce que vous pensez: nous ne sommes jamais rencontré face à face, même si nous nous sommes envoyés beaucoup de mèl, et que nous avions des conférences téléphoniques VOIP hebdomadairement (à 6:30 du mation pour mon fuseau horaire, très tard dans la nuit pour celui de Arjen). Nous avons utilisé dépôt Subversion qu'O'Reilly a mis en place pour nous pour stocker les chapitres, les illustrations, etc... Et nous avons utilisé OpenOffice.org pour écrire les chapitres. Cela était très bien pour moi; j'avais peur lorsque j'ai commencé que nous utilisions Word. Je n'aime aucun type de traitement de texte, mais j'ai été plus heureux avec OO.org qu'avec Microsoft Word.

4 Schema Optimization and indexing (ch04-Schema_Optimization.odt)

  * Baron has written nearly everything.
  * Baron is waiting for feedback on one section.
  * Baron moved redundant material to other chapters.
  * Peter has reviewed and commented.
  * Baron reviewed Peter's comments and revised.
  * Baron reviewed for EXPLAIN appendix.
  * Sent to TR Jan 2nd.
  * Baron rewrote completely.
  * Baron reviewed for grammar and readability.
  * Peter reviewed again.
  * Baron reviewed Peter's comments and revised.
  * Baron revised as per Sheeri.
  * Baron revised as per Igor.
  * Andy edited again.
  * Baron revised.

Utiliser Subversion avec des fichiers binaries n'est pas idéal. Par défaut, Subversion ne verrouille pas les fichiers pour l'édition, il était donc possible d'éditer le même fichier au même moment, et comme les fichiers OO.org sont binaire, il n'était pas possible de les fusionner. Nous avons donc défini la propriété svn:needs-lock sur les fichiers, de façon à ce qu'une seule personne puisse les éditer à une instant donné. Même si cela pourrait paraître problématique, il y avait suffisamment de travail, et je ne pense pas qu'il y ait eu plus d'une fois ou deux où quelqu'un a dû attendre qu'une autre personne libère le verrou sur un fichier. Chaque chapitre était dans un fichier différent. Nous avions également quelque fichiers de méta-données indiquant l'avancement, les éléments à faire, etc... Voici un exemple tiré de notre fichier Statut:

4 Optimisation du schéma et index (ch04-Schema_Optimization.odt)

  * Baron a à peu près tout écrit.
  * Baron attend un retour pour une section.
  * Baron a déplacé des éléments en doublons dans d'autres chapitres.
  * Peter a relu et commenté.
  * Baron a relu les commentaires de Peter et les a pris en compte.
  * Baron a relu pour l'appendice EXPLAIN .
  * Envoyé à la revue technique le 2 janvier.
  * Baron a tout réécrit.
  * Baron a relu pour la grammaire et la lisibilité.
  * Peter a relu de nouveau.
  * Baron a relu les commentaires de Peter et les a pris en compte.
  * Baron a corrigé suivant les remarques de Sheeri.
  * Baron a corrigé suivant les remarques de Igor.
  * Andy a de nouveau édité.
  * Baron a fait des corrections.

Il s'agit de l'état final du fichier; en avançant, nous avions des sous-sections dans ce fichier texte indiquant les étapes suivantes, qui devait faire quoi, etc... Comme vous pouvez le prévoir, à différents moments, chaque section passait à quelque chose comme "ébauche finale terminée", alors qu'avec le recul, elle n'était probablement terminée qu'à 25%.

Retour aux outils: en fait, vous pouvez comparer et fusionner des fichiers depuis OO.org, mais c'est assez rudimentaire. OO.org était agaçant de plusieurs manières; il a beaucoup de bugs qui se mettent en travers du chemin. Certains sont simples, comme la façon qu'a la boîte de dialogue rechercher-remplacer de ne pas se souvenir d'une recherche à l'autre que vous voulez utiliser les expressions règulières. D'autres sont plus sérieux, et font planter le programme, par exemple lorsque vous appliquez une définition de style. O'Reilly possède une maquette qui contient des macros vous aidant à formater des choses avec les styles qu'ils veulent; ainsi, ils sont ensuite capables de convertir les fichiers dans les propres formats. Ils sont plutôt malhabiles, et OO.org ne fonctionne pas si bien que ça avec eux dans beaucoup de cas. J'ai appris certaines trucs pour mieux les utiliser; finalement, j'ai trouvé différentes barres d'outils et boîtes de dialogues dans Writer, et j'ai réussi à les fonctionner à peu prés comme je voulais, ce qui m'a permis d'écrire selon mes désirs. Mais il restait encore beaucoup de choses agaçantes, comme l'impossibilité d'avoir une vue globale. Je ne suis pas sûr que OO.org puisse faire ??? d'une façon ou d'une autre, mais les styles personnalisés d'O'Reilly n'étaient pas reconnu comme étant des niveaux de titre ???outlineable???

Au départ quand Andy éditait des fichiers, il y mettait des commentairs en utilisant la fonctionnalité de Commentaire. Cela ne fonctionnait pas correctement. Les fonctionnalités de commentaire et de relecture de OO.org, tout du moins dans cette version, étaient horribles. Trouver des commentaires dans un texte était extrêmement difficile, il semblait n'y avoir aucun lien entre l'ordre des commentaires et l'ordre dans lequel ils apparaissent dans le texte. Et une fois que jeles avais trouvés, je ne pouvais en fait pas les lire, parce que l'interface ne faisait pas de retour à la ligne, je ne pouvais donc que voir quelques mots à la fois. J'ai donc rapidement convaincu Andy de plutôt mettre ses commentaires dans le texte. Il activait le "Suivi des modifications", qui fonctionnait plutôt bien, et il ne me restait qu'à les relire et les accepter.

Au début, je pensais que je ferai de la relecture et de l'édition, pas que j'écrirai de nouvelles choses. J'ai donc commencé en activant le suivi des modifications. Mais cela rendait le programme vraiment très lent, et je trouvais que a) j'écrivais plus que je n'éditais, et b) lorsque j'éditais, je faisais fondamentalement de la ré-écriture. Je l'ai donc désactivé. Il y a eu quelque fois où je me suis inquiété de perdre le sens originel, mais demander aux autres auteurs de relire mes changements était trop lent. Les autres auteurs avaient tant de travail à faire que au final, nous avons juste réussi à obtenir que Peter écrive le canevas initial, relise ce que j'écrivais à partir de ça, et dans certains cas, le relise une deuxième fois. J'ai dû faire face à cette réalité, et propose un autre plan: extraire les morceaux pertinents qui nécessitait vraiment, vraiment d'être relu et les mettre dans des mails, ce qui représente beaucoup moins de travail pour les autres auteurs pour les parcourir et y répondre, mais il en résultait plus de travail pour moi.

D'autres choses ont également fortement réduit ma productivité: vous ne pouvez séparer en deux panneaux et voir/éditer deux parties du document en même temps; etc, etc, etc... J'insérais des illustrations, et elles disparaissaient lorsque quelqu'un d'autre ouvrait et sauvegardait le fichier. Finalement, je m'en suis sorti. Le plus important était que le travail se fasse.

Relire, ré-écrire et recommencer de zéro

Le livre était une seconde édition. Donc, techniquement, nous relisions et mettions à jour la première édition.

En fait, nous n'avons pas gardé grand chose de la première édition, juste un peu de texte et la plupart des titres et de la structure général. Je veux être prudent sur la façon dont je dis ça, car je ne veux pas critiquer la première édition, mais il était évident que notre travail était de le rendre meilleur. J'ai entendu des gens dire qu'ils aimaient la première édition, et d'autres personnes dire qu'ils pensaient qu'il n'allait pas assez en profondeur. (Espérons que la seconde édition les satisfaira.))

J'ai en fait réalisé que, à part la table des matières, j'ai préféré, si possible, ne pas me rapporter au matériel de la première édition. C'est beaucoup plus de travail de ré-écrire que d'écrire de zéro, à moins que les changements soient vraiment minimals. A quelques endroits, nous pensions que les changements seraient uniquement cosmétiques; cela se terminait presque toujours par beaucoup de travail. Oups!

L'idée originale était que Peter et Vadim essaieraient d'écrire la documentation, et moi, je réécrirais/éditerais (et dans certains cas, ce serait Arjen à ma place), puis Peter le relirait, et Andy l'éditerai,et nous continuerions ainsi jusqu'à ce que ce soit terminé. J'ai rapidement réalisé que ça n'allait pas fonctionner. Ré-écrire représente beaucoup plus de travail que juste écrire à partir d'un canevas détaillé. Je l'ai calculé plusieurs fois, et j'ai découvert qu'il fallait environ 4 fois plus de temps pour ré-écrire et peaufiner le texte que de temps pour simplement écrire les paragraphes.

Auteurs potentiels, notez bien ce point: Le "réglage final" représente largement plus de travail que le processus initial et satisfaisant de coucher les mots sur le papier. Vous pouvez réduire votre travail d'environ 75% si vous travaillez sur un canevas de plus en plus détaillé, longtemps après le moment où vous pensiez que vous deviez commencer à "écrire". C'est en tout cas mon expérience.

Après un peu de réflexion, j'en ai conclu que cela était dû au fait que la ré-écriture ressemble un peu à faire de la rétro-ingénierie, puis de recompiler. Prenons cela par exemple:

De bonnes performances dépendent à la fois d'un schéma et d'un index optimal. Optimiser les paramètres du serveur peut améliorer les performances de quelques pourcents à plusieurs facteurs, mais optimiser un schéma conçu médiocrement et mal indexé peut améliorer les performances de plusieurs ordres de magnitude.

Ce paragraphe n'est pas très clair, mais il n'est pas non plus totalement incompréhensible. Qu'est-ce qu'il faut faire pour l'arranger ? Eh bien, voyons un peu ça... vous devez trouver ce qui est bon et ce qui est mauvais là-dedans. Qu'est-ce qui est flou ? Je pense que "de quelques pourcents à plusieurs facteurs" est plutôt pas très clair. Qu'est-ce que nous essayons de dire là ? Zoom arrière: quel est l'objet de tout le paragraphe ? Je dirai que les éléments principaix de ce paragraphe sont a) vous avez besoin d'avoir à la fois un schéma et une indexation optimaux; b) les réglages peuvent donner un peu d'amélioration, mais le schéma vous en donne beaucoup. Maintenant, nous allons essayer de trouver comment dire cela de façon succincte, et de déterminer ce qu'il faut garder et ce qu'il faut enlever. Ce qui est finalement arrivé à l'impression est ceci :

Optimiser un schéma conçu médiocrement et mal indexé peut améliorer les performances de plusieurs ordres de magnitude. Si vous avez besoin de hautes performances, vous devez concevoir votre schéma et vos index pour les requêtes spécifiques que vous effectuerez.

   Generosity can be Unwise

Plutôt différent, hein ? Il y a eu problablement 4 à 6 révisions entre ces deux versions. Voici un autre avant/après:

    La Générosité peut manquer de Sagesse.

Une erreur courante est de supposer que puisque l'espace consommée pour de petites chaînes de caractères est le même pour VARCHAR(10) et VARCHAR(200), vous pouvez simplement définir la longueur maximale à une valeur plus grande. En fait, cela pénaliser fortement les performances, car les chaînes de caractères sont souvant allouées en interne comme un objet de taille fixe. Ainsi VARCHAR(200) occupera plus de place en mémoire, en particulier pour les tris ou les opérations qui utilisent des talbes temporaires en mémoire. La même chose arrive avec le tri des fichiers qui utilise des tables temporaires sur le disque. La meilleure stratégie est d'alloué l'espace dont vous avez besoin.

   Generosity Can Be Unwise

   Storing the value ‘hello’ requires the same amount of space in a VARCHAR(5) and a VARCHAR(200) column. Is there any advantage to using the shorter column?

… et après :

    La Générosité peut manquer de Sagesse

    Stocker la valeur 'bonjour' nécessite la même quantité d'espace dans une colonne VARCHAR(7) que dans une colonne VARCHAR(200). Existe-il un avantage à utiliser une colonne plus petite ?

En fait, il y a un gros avantage. La colonne la plus grande peut utiliser plus de mémoire, car MySQL alloue souvent des blocs de mémoire de taille fixe pour gérer les valeurs en interne. C'est en particulier mauvais pour trier ou pour des opérations qui utilisent des tables temporaires en mémoire. La même chose se produit avec le tri des fichiers qui utilise des tables temporaires sur le disque. La meilleure stratégie est d'allouer uniquement l'espace dont vous avez réellement besoin.

Le processus prend une quantité de temps incroyable, et même si vous pensez que c'est le travail de l'éditeur, dans mon expérience d'écriture de livre, cela était principalement mon travail, pas celui de l'éditeur. Si je ne l'avais pas fait, soit a) l'éditeur ne l'aurait pas fait et j'aurais eu une tonne de travail à faire pour relire les éditions (ce n'est pas une petite tâche) soit b) le livre aurait été d'une moins bonne qualité.

En conséquence, nous avons rapidement abandonné l'idée que Peter et Vadim écrirait le premier brouillon et que je partirai de là. Les quelques chapitres déjà écrits de cette façon représentaient une quantité stupéfiante de travail à faire, et j'ai dû y revenir encore et encore. A la place, j'ai demandé à Peter d'écrire un canevas détaillé de points importants et des fragments d'idées. Il était beaucoup plus facile de partir de cela pour écrire. Je lui demandai essentiellement de remplir de façon itérative le canevas pour moi, ce qui est, je le pense désormais, une meilleure façon d'écrire ce type de matériau dont l'organisation est complexe. (Je ne pense toutefois pas que c'est une bonne solution pour écrire une narration complexe; ce n'est pas une approche qui s'applique à tout.)

Je ne retrouve plus un exemple de ce canevas brut, mais je pense que vous avez compris l'idée.

Une autre chose qui a conduit à du travail supplémentaire était lorsque le canevas n'était pas suffisamment détaillé pour qu'on puisse commencer à travailler avec. Par exemple, nous avions initialement mis ensembles les chapitres sur la réplication, le redimensionnement, la haute disponibilité, etc... Cela paraissait raisonnable, mais c'était parce que nous n'avions pas assez détaillé la structure. Après avoir commencé à lui donner de la consistance, il nous est apparu clairement que ce serait un chapitre monstrueux, et nous l'avons séparé en plusieurs morceaux, donc plus de travail. Nous avons également enlevé le chapitre "Retour aux fondamentaux" de la première édition, et nous avons fini par supprimer ou déplacer beaucoup de matériel qui n'était pas à la bonne place ou qui était dupliqué. Tout cela nous a demandé toujours plus de travail.

Je dirai qu'éviter de céder à la tentation d'écrire, et décrire un canevas détaillé à l'extrême, est une activité à haute valeur ajoutée pour écrire un livre dont la hiérarchie est organisé comme celui-ci. N'écrivez pas de la prose. A l'instant où vous commencez à écrire des phrases, vous commencez à structurer vos pensées d'une manière qui crée des relations complexes entre les mots, les phrases, et les paragraphes. Les démêler et les remettre ensuite ensemble est parfois violent. Il y eut des fois où je regardai quelque chose en sachant que c'était horrible mais il m'était impossible de trouver une manière différente de le dire. J'avais des oeilléres car j'étais coincé dans ce qui était déjà là.

Il nous arrivait souvent d'écrire des choses d'une façon qui nous semblait approriée, mais nous découvrions alors qu'il était nécessaire d'intervertir quelques paragraphes ou pages. L'ordre dans lequel nous les avions écrits au départ faisait couler le texte d'une certaine façon, qui n'était plus approriée après que nous les ayons bougé. Nettoyer cela était très difficile. Je conseille à des auteurs potentiels de prévoir beaucoup de tripatouillage sur le plan, donc Faites un plan beaucoup plus détaillé que ce que vous pensiez devoir faire. Cela donne beaucoup moins de travail de réarranger des morceaux de chapitre quand ils sont encore sous forme de canevas.

A partir d'un certain point, lorsque vous avez écrit une vaste quantité de texte, il devient difficile de garder une trace de où est quoi. Je me suis retrouvé à me dire "J'ai écris quelque chose à propos de ça quelque part" et à le chercher, mais être incapable de le retrouver. Plus tard, en éditant un autre chapitre, je tombais sur ce que je cherchais, mais je n'arrivais alors plus à me souvenir où était l'autre endroit. Parfois, j'utilisais diffrents mots à deux endroits, il était donc impossible d'en trouver un en cherchant dans les mots-clés de l'autre. Nous avons eu beaucoup de matériel en doublon à certains endroits, et il était vraiment difficile de régler ça. Une partie du problème venait du fait que le livre était organisé de façon hiérarchiue, et que le vieux problème de la hiérarchie unique commençait à nous attaquer. Les choses appartiennent à plusieurs endroits, mais elles ne peuvent aller qu'à un seul. Un bon exemple concerne les réglages du serveur et les variables de statut. Devons-nous en parler dans le chapitre sur les réglages du serveur, ou à l'endroit où nous montrons comment interpréter les variables de statut ? Ils appartiennent aux deux endroits, et nous avons finalement terminé avec quelques recouvrements. Régler cela a représenté beaucoup de travail. Je ne sais pas comment atténuer ce problème, à part avec une bonne vue du plan, ce qui manque dans OO.org.

Beaucoup de ce que nous avons écrit nécessitait des recherches apprfondies. Parfois, il suffisait de jeter un coup d'œil au manuel MySQL (qui n'est pas toujours juste, donc tout devait être vérfié), mais nous devions aussi souvent aller lire du code source ou contacter l'auteur d'un programme. Occasionnellement, nous devions également lancer de longs tests ou des benchmarks.

Ce que j'ai appris de cela, c'est que les recherches peuvent durer éternellement. Vous êtes soit en train d'essayer de comprendre quelque chose, soit vous êtes dans l'attente d'un pauvre programmeur qui a des milliers de mails dans sa boîte de réception.

Voici un exemple: qu'est-ce que avgrq-sz signifie réellemetn dans iostat ? La page du manuel est plutôt déroutante. Elle dit "La taille moyenne (en secteurs) des requêtes qui ont été envoyées au périphérique." Pour découvrir ce que cela veut réellement dire, j'ai dû lire les sources de iostat, les sources du noyau, et la documentation du noyau. Cela m'a pris beaucoup de temps. J'ai ensuite confirmé mes découvertes avec l'auteur de iostat.

Nous avons effectué beaucoup de recherches sur les fonctionnalités avancées de MySQL, comme les procédures stockées, le cache de requête, etc... Et beaucoup, beaucoup! , dans InnoDB. Nous voulions particulièrement apprendre comment ces fonctionnalités interagissait entre elles. Par exemple, comment InnoDB interagit avec le cache de requête ? Ce n'est pas du tout documenté. Chaque chose prend beaucoup de temps.

Nous avons également réalisé beaucoup de tests de performances. Les tests de performances sont très consommateurs de temps, également.

Prévoyez de prendre plus de temps pour la recherche que vous pensiez que vous devriez. Jay Pipes m'a dit prévoir environ une demi-page par jour, et je pense que cela doit être correct lorsque vous devez effectuer des recherches pour la plupart du matériel de chaque page.

Ecrire clairement

Travailler avec l'éditeur a été une expérience enrichissante. Je savais que je possédais des points faibles dans mon écriture (et j'en ai encore), mais je ne savais pas ce qu'ils étaient. J'étais fermement décidé à ce que le livre soit clair et facile à comprendre. C'est difficile quand vous avez un livre vraiment pointu et complexe, mais c'est encore plus important.

Par conséquent, j'ai créé un ensemble d'heuristique pour m'aider à trouver les endroits où quelque chose nécessite de l'attention. Ce n'était pas un processus parfait, mais cela m'a beaucoup aidé. Je créait alors un fichier texte avec des expressions régulières, et chercher des correspondances. Lorsque je les trouvai, je réfléchissai à ce que je devais faire avec.

   Things belong in multiple places, but they can only go in one place.

   Things belong in multiple places, but they can go in only one place.

Voici un exemple: le mot "seulement". J'ai l'habitude de mal l'utiliser, et je ne le savais pas. Mais j'ai aprris, parce que j'ai observé ce que Andy corrigeait, et j'ai noté le comportement. J'ai ajouté le mot "seulement" à mon fichier texte d'expressions régulières. Voici un exemple de ma mauvaise utilisation de ce mot :

   Les choses appartiennent à plusieurs endroits, mais ils peuvent aller seulement à un endroit.

(Hmmm, c'est une phrase que j'ai écrit dans ce post!) Voici ce que j'aurai dû écrire :

   Les choses appartiennent à plusieurs endroits, mais ils ne peuvent aller qu'à un seul endroit.

Passive voice:

 (were|was|is|are|has been|be)( [a-zA-Z]+)? [a-zA-Z]+ed\>

 Repeated words:

 \<([a-zA-Z]+) +\1\>

 Confusing possessives:

 the ([a-zA-Z]+) of the

 Things to look out for:

 while|since|\<using|in order|of course|whether|allow|ensure|only|as (we|you)|without saying|obviously|clearly|needless|again,

 Finding pseudo-cross-references:

 ((Figure|Table) [0-9])|TODO|XREF|MARK_

 An awkward phrase that showed up a lot:

 \<by [a-zA-Z]+ing\>

A la fin, mon fichier d'expressions régulières ressemblit à cela:

Mode passif:

 (were|was|is|are|has been|be)( [a-zA-Z]+)? [a-zA-Z]+ed\>

Mots répétés:

 \<([a-zA-Z]+) +\1\>

Confusion de possessif:

 the ([a-zA-Z]+) of the

Choses à chercher:

 while|since|\<using|in order|of course|whether|allow|ensure|only|as (we|you)|without saying|obviously|clearly|needless|again,

Chercher des pseudo-références-croisées :

 ((Figure|Table) [0-9])|TODO|XREF|MARK_

Une expression bizarre qui apparaît souvent :

 \<by [a-zA-Z]+ing\>

Ces expressions m'ont aidé à attraper des constructions comme "the tail of the dog", qui peut se raccourcir "the dog's tail". Ou quelque chose que j'ai noté souvent dans le contenu existant: "En utilisant mysqldump, vous pouvez décharger les données", devient "Vous pouvez décharger les données avec mysqldump" (La dernière ligne du fichier permet de détecter celle-là). J'ai essayé de faire dire à mes phrases, autant que possible, "qui fait quoi pour faire quoi". Si vous ne pouvez pas répondre à cette question à propos d'une phrase, à mon avis, c'est que ce n'est pas clair. J'ai essayé d'utiliser des mots plus courts lorsque c'était possible:"permettre" peut souvent être remplacé par "laisser", et comme bonus, cela transforme souvent une expression en un seul mot: "Ces réglages vous permettent de..." devient "Ces règlages vous laissent..."

Des expressions comme "bien sûr" m'indiquent en général que j'ai été paresseux. "Bien sûr" veut en fait dire "c'est évident, mais je le dis quand même". Alors pourquoi l'écrire ? Cependant, le plus souvent "bien sûr" est un raccourci pour dire "Je crois cela, mais je ne sais pas pourquoi, et c'est difficile à expliquer, alors je laisse juste entendre que c'est évident et que vous ne devriez pas me demander de l'expliquer". Beaucoup d'autres expressions dans ma liste sont simplement de mauvaises habitudes mentales dans lesquelles je suis tombées, comme "afin de", qui peut en général être raccourci par "pour".

Mon père m'a appris que j'utilisais trop "que". "Elle dit que la tarte était bonne" devient "???". Parfois, j'allais trop loin avec cela. Par exemple, "Mon père m'a appris j'utilisais trop "que" est exagéré; il faut un "que" supplémentaire pour que cela glisse mieux. L'éditeur a remise quelque "que" dans le texte.

Le mode passif est un tueur absolu, il trouble le lecteur, même s'il ne le remarque pas forcément, et rend plus difficile à comprendre et à retenir ce qu'il lit. Voici un exemple que j'ai trouvé grâce à mon expression régulière: "Pour certaine sorganisations, ce problème est résolu par une combinaison de" devient "Certaines organisations résolvent ce problème par une combinaison de". La clarté des phrases est réduite par peu de choses autant que lorsque le mode passif est utilisé par l'auteur. (Vous êtes censé rire).

Peu importe à quel point vous croyez bien écrire, préparez-vous à mettre votre ego de côté. Un éditeur trouvera toujours des moyens de rendre vos écrits encore meilleurs.

Après avoir appliqué mes heuristiques pour m'aider à trouver mes points fabiles, j'ai pensé que je pouvais faire encore mieux. Je suis un programmeur Perl, pas vrai ? Exact. J'ai donc récupéré quelques modules sur CPAN, écrit un petit processus qui extrait le texte des fichiers et le nettoie un peu, puis effecture une analyse des phrases dans les fichiers. J'ai utilisé plusieurs métriques standards de lisibilité pour analyser les phrases individuellement et les paragraphes entiers; Flog, Flesch, et Flesh-Kincaid. Mais ils n'étaient pas suffisamment bons, et l'algorithme de césure n'était pas suffisamment bon pour mesurer le nombre de syllabes correctement. Je me suis donc tourné vers le système ultime pour faire des césures dans la langue anglaise : TeX. Il possède des règles pour faire des césures de façon extrêmement juste, avec toutes sortes de cas spéciaux. ("Les thé-rapeutes qui prêc-hent la nu-it" est un exemple classique de mauvaise césure.) J'ai découpé les phrases en syllabes avec un processus personnalisé pour brancher Perl sur les routines de césures de TeX à travers un autre module CPAN, puis j'ai classé les phrases et les paragraphes par nombre de syllabes. J'ai ensuite combiné tous ces métriques et créé un rapport indiquant quelles étaient les pires parties. J'ai alors jeté un coup d'oeil aux 30 phrases qui avaient le plus mauvais score, et j'ai trouvé de cette façon beaucoup de problèmes.

Cela a été un exercice enrichissant; il m'a aidé à avoir une vision nouvelle sur le texte que je regardais depuis des mois, m'a réellement aidé à trouver les mauvais endroits dans le texte. Mais ce n'était pas encore suffisant. Plus d'informations à ce propos dans la section suivante.

Du concept à la réalisation

Le processus haut-niveau pour qu'un chapitre puisse être envoyé à la revue technique ressemble à ça :

• Faire le canevas
• Refaire le canevas
• Remplir le canevas
• Edition initiale
• Envoi aux autres auteurs pour relecture
• Corriger
• Envoyer à l'éditeur
• Corriger
• Répéter, répéter, répéter ...

C'est en gros ce qu'il faut faire pour réussir à obtenir quelque chose prêt à être envoyer à la revue technique. Chaque chapitre est allé à l'éditeur ou à son assistant au moins trois fois, et de nouveau vers Peter au moins une ou deux fois. Les relectures de Peter sont exhaustives (et exténuantes) et il y avait parfois beaucoup de travail pour comprendre ce qu'on peut en faire. Il ajoutait également dans de nombreux cas beaucoup de profondeur, ce qui nécessitait une réécriture et de définir un nouveau plan. (Vous vous souvenez de mon conseil sur la définition du canevas jusqu'à un niveau de détail hallucinant avant de commencer à écrire ?). Chacune de ces étapes prenait également beaucoup de temps, car c'était aussi beaucoup de travail pour Peter. Il faisait également beaucoup de conseils sur site, déplaçant toute sa famille aux Etats-Unis, et continuant à faire tourner Percona en même temps. Honnêtement, je ne sais pas comment il a réussi.

A la "fin" de ce processus, les chapitres étaient raisonnablement complets au niveau des fonctionnalités, mais avec de larges sections marquées A FAIRE, car elles attendaient que l'un des auteurs, un "appel externe réseau" pour Heikki ou quelqu'un d'autre, ou un test de performance. Pourtant, il fallait bien que les choses aillent à la revue technique à un moment ou à un autre. A ce moment-là, le processus était le suivant :

• Envoyer à la revue technique
• Continuer à travailler
• Recevoir des commentaires
• Corriger, attendre, attendre, attendre
• Recevoir des commentaires d'un autre relecteur, corriger de nouveau, et répéter jusquà ce que ce soit terminé

Chacun a un vie bien remplie, et nous n'avons pas pu envoyer les premiers chapitres à la revue technique avant les vacances, le pire moment pour demander à des gens de le faire. Et il y avait tant à faire que je ne pouvais pas attendre que toutes les retours de la revue technique reviennent pour commencer à corriger. En conséquence, je reevais des commentaires de Sheeri, et je devais les mettre en accord avec les modifications que j'avais effectué en réaction à Roland, et alors les commentaires de Pascal arrivait et je me retrouvais à 2h du matin à me demander :" mais pourquoi est-ce qu'il me dit ça! Je l'ai déjà corrigé!" Cette réaction dépendait de mon état de fatigue et depuis combien de temps je travaillais sur ce livre, mais pas de mon sentiment réel envers Pascal.

Nous n'avons également pas clairement indiqué aux relecteurs qu'ils étaient censé relire, pas faire de l'édition. J'essaierai de ne pas refaire cette erreur. Certains des relecteurs ont passé beaucoup de temps à corriger la grammaire et le style. Malheureusement, c'était de l'énergie perdu, le matériel était d'une qualité trop médiocre pour que l'on se préoccupe de corriger le style et la grammaire (et le style est la responsabilité de l'auteur et de l'éditeur, pas celui des relecteurs techniques). Il est en fait également impossible d'accepter les changements qu'ils ont fait aux fichiers, il n'y a pas moyen de fusionner ensemble les changements de 5 relecteurs techniques, j'ai donc ouvert les fichiers de relecture séparément, et fait des allers-retours entre eux et ma copie de travail. Les éditions ont encore ajoutése de nouvelles choses qu'il fallait également que je regarde; c'est vraiment la mauvaise étape pour faire autre chose que l'édition de haut-niveau (au niveau de l'organisation globale, par exemple). L'étape de relecture technique consiste simplement à chercher des erreurs factuels, ou des choses qui sont techniquement ambigues ou discutable. Comme vous le verrez, l'étape d'édition allait arriver plus tard.

Après la relecture technique et beaucoup d'autres répétitions d'édition et de correction, les chapitres furent considérées comme prêts pour la production. Il n'existe pas de moyen pour se préparer à la quantité de travail nécessaire pour arriver à cette étape. En fait, cela vient peut-être de démarrer avec du matériel de relativement piètre qualité (je parle du contenu brut de Peter et Vadim, pas du matériel issu de la première édition, une partie du matériel était un espèce de dump hexadécimal combiné avec des astuces provenant de posts de blogs, passé à travers un obfuscateur). Quoiqu'il en soit, la chose la plus bizarre qui pouvait arriver s'est produite : après avoir marqué un chapitre comme étant prêt pour la production dans le méta-fichier de Statut, j'ai jeté un coup d'oeil sur le chapitre, et j'ai découvert toutes sortes de notes A FAIRE qui n'étaient pas résolues. Je le jure, je pensais les avoir toute réglées. Et beaucoup d'entre elles nécessitait une quantité énorme de travail. Et j'ai dû admettre que le chapitre était loin d'être fini, et j'ai dû recommencer le travail dessus.

Finalement, ils finirent par être terminés. Nous les avons alors tous empaquetés et envoyés à la production. Et pour la 99ème fois, j'ai dit à tout le monde que le livre était terminé. J'étais pourtant loin d'avoir raison.

A ce moment, pour la première fois, je pensai savoir à quoi m'attendre. Je savais qu'il y avait un directeur de production, et qu'à ce moment-là il partirai à une équipe qui le transformerai dans un programme quelconque de typographie, et finalement à l'impression. Mais là encore, personne ne m'en avait parlé, même si j'ai demandé. Quoiqu'il en soit, c'est toujours plus facile de voir les choses avec du recul, voici donc ce qui s'est passé:

• Directeur de production
• Correction
• Retour au directeur de production
• Correction
• Au reste de l'équipe de production

Le directeur de production devait juste vérifier l'orthographe et la grammaire, n'est-ce pas ? Je pense que quelqu'un m'a dit ça. Au lieu de ça, elle a scruté le livre à un niveau de détail tellement incroyable que je ne pouvais pas le croire. Et elle a proposé des changements majeurs à presque tous les paragraphes du livre entier. Elle a fait tellement de changements qu'il m'a fallu au moins un jour, parfois deux ou trois, pour corriger chaque chapitre. Cela représentait des semaines de travail que je n'avais pas vu venir, chaque week-end, chaque nuit, tout le temps, exactement comme lorsque j'écrivais. Et ces changements étaient nécessaires. Elle a trouvé chaque petite phrase ambigue, chaque contradiction entre différentes parties du livre, des accolades fermantes manquantes dans les exemples de code, des paragraphes qui appartiennent à d'autres chapitres, des phrases qui avaient besoin d'être bougé, des virgules au mauvaise endroit, et beaucoup d'autres. Elle était une machine d'édition absolue. Voici un exemple :

Rappelez-vous, c'était après que l'éditeur et l'assistant de l'éditeur soit passés environ cinq fois à travers tout le matériel. Je ne m'attendais pas à autant de correction à ce moment-là; je pensais qu'il suffirait de corriger quelques virgules et apostrophes qui étaient à la mauvaise place.

Elle est passée à travers le livre tout entier avec ce niveau de détail, ce n'est pas une section particulièrement éditée, mais elle est représentative. Cela a été bien qu'elle le fasse, mais ça a représenté vraiment beaucoup plus de travail que ce que je pensai devoir faire à cette étape.

Cela a été rendu pire par le fait que le processus d'édition en production était fait sous Microsoft Word. Je n'ai pas et je n'utilise pas Word. Cela aurait pu être OK, mais comme je l'ai déjà mentionné, la gestion de marques et des corrections est plutôt limité dans OO.org. L'éditeur utilisait énormément les balises de commentaire pour clarifier beaucoup des questions qu'elle avait. Ce sont précisément les points faibles d'OO.org. J'ai donc fini par utiliser le portable de ma femme, qui a Word, pour corriger les fichiers. Cela m'a rappelé combien Word pouvait être buggé, je dirai même plus buggé que OO.org. Word a planté je ne sais pas combien de fois, et les problèmes d'affichage et de formatage étaient tout simplement ridicules. Parfois des pages entières étaient perdues ou mélangées. J'ai vu le milieu d'un paragraphe à la fin d'une page, passer au début de la page suivante, et vu du contenu qui aurait dû se trouver plus loin dans le livre. Je cliquais quelque part pour insérer une note ou éditer un changement, et il se mettait à paniquer et à se retrouver au début du fichier; ou simplement il plantait. Le processus était beaucoup plus lent que ce qu'il aurait dû être. J'en reste donc à mon avis qu'un traitement de texte est un outil terrible pour écrire un livre.

Mais finalement, je m'en suis sorti. Et alors, après tout cela, j'en avais vraiment fini. Vraiment ? Eud, non. A ce moment, j'ai le planning réel des étapes restantes.

• Révision
• Relecture de la révision
• Entrer la révision
• Conversion
• Vérification des sources
• Lancement
• Contrôle de Qualité 1 (CQ1) / Correction des épreuves
• Création de l'index
• Entrer les éditions QC1 / Découpage en page
• Copie de la couverture pour la Production/Conception
• QC2
• Entrer les éditions QC2
• Revision de l'index
• Estimation des pages terminée
• Index final terminé
• Envoi de la couverture à l'impression
•  ???? OTD ???? du Contrôle de Qualité
• Envoi du livre à l'impression
• Sortie du livre
• Sortie en magasin

Tout cela n'était pas mon boulot, mais j'ai été impliqué dans une grande partie, cela s'est produit en peu de semaines. Voulez-vous deviner combien de ces étapes m'ont demandé beaucoup de travail ?

Indice : J'étais assis à la cérémonie de remise des diplômes de mon frère à relire l'index pour essayer de ne pas faire davantage glisser davantage le planning. Et j'ai passé mes week-ends et mes soirées à corriger les épreuves et à être sûr que tout était converti correctement pour la mise en page finale.

Quelque chose d'autre est alors arrivé. L'illustrateur n'avait pas commencé à dessiner les illustrations avant les étapes de copie de production et de contrôle de qualité listées au-dessus. Ce que cela veut dire, c'est que contrairement au texte, les illustrations n'ont pas eu 10 à 15 fois le parcours corrections, commentaires, et re-travail. Cela a vraiment été fait à la dernière minute. Heureusement, l'illustrateur a été capable de faire un travail impressionant à partir de pas grand chose. Malheureusement, cela voulut dire qu'une ou deux illustrations n'étaient pas fabuleuses, au moins pour mes standards, même s'il s'agissait vraiment de dessins professionnels. Je parle du contenu des illustrations, pas de la façon dont ils étaient dessinés. J'aurai aimé que certaines illustrations présentent les concepts plus clairement. J'ai essayé d'utiliser les illustrations pour montrer ce que le texte ne décrivait pas correctement; une ou deux de ces illustrations aurait pu être meilleur. Hélas.

Le planning n'a pas ét