Retour d'expérience sur la rédaction d'un livre technique

  • leanpub book
  • rails

Publié le 2019-11-11

IntĂ©ressĂ© pour crĂ©er un API avec Ruby on Rails? Jette un coup d'Ɠil Ă  mon livre: API on Rails 6. Tu peux tĂ©lĂ©charger une version gratuite au format PDF sur Github. Si tu aimes mon travail tu peux acheter un version payante sur Leanpub.

En début d'année 2019 j'ai été contacté par Developpez.com qui cherchait des personnes pour écrire des articles. J'ai donc répondu positivement pour participer sur le sujet du framework Ruby on Rails.

On m'a ainsi proposé de traduire une partie du livre APIs on Rails Building REST APIs with Rails de Abraham Kuri Vargas. Ce livre est un grand tutoriel de plus de 200 pages pour construire une API évolutive avec Ruby on Rails en suivant les bonnes pratiques.

Je me suis dit que ça pouvait ĂȘtre une bonne expĂ©rience et je me suis lancĂ© dans cette aventure.

Le projet était non maintenu et la version du framework étudié obsolÚte. Les exemples n'étaient donc plus valides et il fallait les reprendre. Le bordel. J'ai essayé de contacter l'auteur mais en vain.

Je suis donc reparti de zéro et je me suis lancé dans la réécriture du livre. Et tant qu'à réécrire, je me suis dit que j'allais aussi le traduire dans la langue de MoliÚre.

Voici donc mon retour d'expérience sur la rédaction d'un livre de plus de 200 pages en anglais et en français.

Comment Ă©crire un livre?

Si tu veux écrire un livre, sache que c'est chronophage. J'ai donc fait en sorte que ça me prenne le moins de temps possible. Je ne prétends pas avoir la meilleure solution. Voici juste la mienne.

RĂ©daction

Pour la rédaction je voulais un systÚme qui me permette de versionner mon travail et qu'il puisse inclure des morceaux de code. Beaucoup de morceaux de code.

Je me suis donc tout d'abord tourné vers LaTeX qui s'est avéré trop rigide. Mon principal problÚme était d'avoir une bonne coloration syntaxique. Quelques solutions existent mais elles restent assez limitées.

Je me suis donc tournĂ© vers le format Markdown avec l'outil Pandoc. Cet outil est absolument gĂ©nial mais j'ai fini par rencontrer les mĂȘmes problĂšmes qu'avec LaTeX puisque Pandoc s'appuie sur une conversion en LaTeX pour ensuite la convertir en PDF.

Et puis j'ai découvert Asciidoctor. Il s'agit d'une syntaxe qui apporte des fonctionnalités supplémentaires au Markdown comme la gestion de différents fichiers, les notes de bas de page, les notes internes, les commentaires et j'en passe. Bref, c'est la syntaxe Markdown avec la puissance de LaTeX. Cela m'a aussi permis d'exporter mon livre en PDF, EPUB et MOBI facilement et de personnaliser le thÚme de mon livre.

Pour Ă©crire, il suffit ensuite juste d'avoir un Ă©diteur de texte classique comme VSCode, Atom ou mĂȘme un Bloc Note sur Windows. Pour le versionner j'utilise Git et je publie sur Github .

Workflow

Le workflow que j'ai suivi Ă©tait le suivant:

  1. refaire les exemples de code de mon cÎté dans un projet Github séparé
  2. retravailler la version anglaise en fonction des modifications que je venais d'apporter
  3. coller la version anglaise dans un fichier
  4. faire des traductions en mode copié / collé dans Deepl
  5. corriger la traduction (car c'est loin d'ĂȘtre parfait)
  6. coller la version française dans un fichier

Le premier problĂšme que j'ai rencontrĂ© a Ă©tĂ© de gĂ©rer tout ce processus qui mĂȘle l'Ă©criture du livre en anglais et en français. En rajoutant la gestion du projet crĂ©Ă© tout au long de ce livre ça a Ă©tĂ© difficile. Avec le recul j'aurais dĂ» tout laisser en français et peut ĂȘtre traduire Ă  la fin.

Ensuite je me suis fixé:

  • deux rĂ©Ă©critures par chapitre : une assez rapide et une plus approfondie
  • deux relectures par chapitre (dont une de ma copine qui m'a beaucoup aidĂ©)
  • une partie promotion (j'en parlerai plus loin)

Open Source

Le workflow de publication d'article sur développez.com m'a semblé vraiment compliqué a utiliser et il m'a découragé. Je me suis donc dit que j'allais le rendre Open Source sur Github en citant bien sûr l'oeuvre originale.

J'ai été vraiment surpris de l'aide de la communauté open source. Voici les chiffres du projet sur Github.

  • 8 contributeurs
  • 17 pull requests
  • 92 stars
  • 21 fork

J'ai reçu des pull request qui corrigeaient des erreurs de syntaxe, des liens cassĂ©s et des formulations douteuses. Pour anecdote, j'ai mĂȘme Ă©tĂ© contactĂ© par un russe qui Ă©tait intĂ©ressĂ© pour traduire le livre. Il a juste eu besoin de forker le projet et crĂ©er un dossier ru. C'Ă©tait top.

L'open source donne vraiment la sensation que le livre est vivant.

Lorsque le livre est terminé ou que j'ai fixé des erreurs, je fais une release sur Github et j'attache les fichiers PDF, EPUB et MOBI. Ainsi n'importe qui peut le lire gratuitement sur le support de son choix.

Publication du livre

Je me suis dit que tant qu'à faire, j'allais publier le livre. Cela m'a apporté une visibilité et m'a permis aussi de gagner un peu d'argent.

J'ai regardé un peu du cÎté d'Amazon mais cela m'a semblé trop compliqué car il fallait se créer un compte, choisir la bonne taxe et le publier. Les commissions sont aussi bien plus élevées. J'ai donc abandonné rapidement, tant pis pour ce bon vieux Jeff.

J'ai choisi Leanpub pour sa facilitĂ© et aussi le fait que le prix peut ĂȘtre libre.

J'ai donc publié au total 4 versions:

Au final, voici tous les chiffres des royalties, c'est Ă  dire ce qui va dans ma poche aprĂšs la commissions de Leanpub.

Livre Royalties
API on Rails 5 (EN) $160.63
API on Rails 5 (FR) $15.98
API on Rails 6 (EN) $473.22
API on Rails 6 (FR) $20.78
Total $670.61

J'ai été vraiment surpris de vendre "autant". Ces chiffres ont pour moi vraiment un cÎté motivant qui me pousse à maintenir le projet.

Les chiffres sont aussi à remettre dans le contexte. Cela ma demandé énormément de travail qu'il est difficile de quantifier. A vu de nez je dirais entre 500 et 1000 heures. Cela donne donc un salaire horaire de 1.34 $ / heure. Alors oui, clairement je ne fais pas ça pour l'argent. Mais ça a été pour moi plus une excellente experience rémunérée.

On voit aussi que la version anglophone se vend 17 fois mieux que la version francophone. La premiĂšre conclusion que je peux donner c'est qu' il faut traduire votre ouvrage dans la langue de Shakespeare.

Promotion

Une fois le livre terminé commence la partie de la promotion. C'est une partie assez étrangÚre pour moi et j'ai fait un peu au feeling. J'en ai donc simplement parlé sur les réseaux sociaux spécialisés. C'est à dire:

  • Hacker New qui est une communautĂ© trĂšs exigeante oĂč j'ai eu trĂšs peu de retours
  • Le journal du Hacker qui est une communautĂ© française donc beaucoup plus restreinte
  • Reddit, qui est la communautĂ© la plus active oĂč j'ai eu le plus de retours

J'ai eu des retours négatifs mais aussi d'excellents retour par mail qui sont trÚs gratifiants.

Conclusion

En conclusion je pense que j'ai fait l'erreur de vouloir aller trop vite car j'ai entamé la publication alors que mon livre comportait des petites fautes d'orthographe et des erreurs de syntaxe. La communauté spécialisée (en particulier Hacker News) est assez intransigeante là dessus.

C'est en revanche une expérience exceptionnelle qui m'a apporté beaucoup de satisfaction personnelle. Ce projet m'a aussi permis de mettre un pied dans l'open Source et de maintenir un petit projet.

Articles liés