"authorimage.jpg", "greetings"=>"Hi there! My name is Yehonathan Sharvit. I'm a software developer, author and speaker. My passion is to make interesting things easy to understand. I hope you will enjoy the articles."}"> "authorimage.jpg", "greetings"=>"Hi there! My name is Yehonathan Sharvit. I'm a software developer, author and speaker. My passion is to make interesting things easy to understand. I hope you will enjoy the articles."}" />

A hundred things I learned writing my first technical book “Data-Oriented Programming”

That’s work in progress!

https://twitter.com/threadapalooza https://twitter.com/dan_abramov/status/1470613731071696896

  1. Writing a technical book is much harder than writing blog posts.
  2. Writing my first technical book without a publisher would have been a MISSION: IMPOSSIBLE!
  3. Each piece of the book content must be clear and interesting. Each part, each chapter, each section, each paragraph, each sentence.
  4. Clear is more important that interesting. If something is not clear to your reader, it cannot be interesting for for them.
  5. A possible way to make things clear is go from concrete to abstract.
  6. A possible way to make things interesting is to teach the material as a story.
  7. The “why” is more important than the “what”.
  8. The “what” is more important than the “how”.
  9. An average writer makes the reader think the author is smart. A good writer makes the reader think the reader is smart.
  10. A technical book is written for MQRs (Minimal Qualified Readers). It allows the author to assume what knowledge the readers already have.
  11. Front matter is the last part an author writes.
  12. Checking book sales could be addictive.
  13. Making a good Table of Contents is crucial as it is the first part of the book potential readers will encounter.
  14. Making a good Table of Contents is hard as you need to figure out what you really want to talk about.
  15. The Table of Contents might evolve as you write the book.
  16. Never assume that your readers will read the next chapter only because they have enjoyed the previous chapter.
  17. You should always tell your readers why what you are teaching is important and relevant for them.
  18. Before writing a chapter, you should formulate to yourself what is the main objective of the chapter.
  19. If a chapter has two main objectives, it’s a sign that you should split it into two chapters.
  20. A chapter should be treated like a piece of software. You should resist the temptation of writing the chapter contents without a plan.
  21. A possible way to make things interesting is to use examples.
  22. A possible way to make things clear is to use examples with increasing level of difficulty.
  23. Do not hesitate to highlight sentences that convey an important message.
  24. It’s OK to engage in writing a technical book without mastering every topic you want to cover in your book.
  25. Writing technical book involves a descent amount of research even if you consider yourself as an expert in the field.
  26. Finding attractive but accurate titles to book chapters is an art.
  27. You can learn a lot from a failed attempt to write a book, provided that you put your ago aside.
  28. If you try to write a Wikipedia article about the topic of your book before it is mentioned by other sources, it will be rejected.
  29. AsciiDoc rocks!
  30. PlantUML rocks!
  31. NeoVim rocks!
  32. People on Reddit could feel hurt by opinions that take them out of their comfort zone.
  33. On Reddit, when people feel hurt, they could become violent.
  34. It makes lot of sense to use a source control software for your manuscript.
  35. You need to be very careful not to hurt the sensitivity of any of your readers.
  36. A good technical reviewer is an asset.
  37. Your publisher is your partner.
  38. You could make more dollars per copy by self-publishing but you’d probably sell much less copies.
  39. Asking early feedback from external reviewers is a great source of improvement.
  40. Releasing an early version of the book (approx. when the first third is ready) allows you to find out if the topic of your book is interesting.
  41. Finding a good book title is hard.
  42. Finding a good book subtitle is even harder.
  43. Having your book featured on HackerNews home page do not mean selling lots of copies.
  44. Twitter is a great medium to share ideas from a book.
  45. If you are lucky, writing a book could sometimes take you to flow.
  46. My real motivation for writing a book was neither to be famous nor to be rich. It only wanted to accomplish a child’s dream.
  47. It’s hard to find your writing style.
  48. Once you have found the your writing style, the writing flows.
  49. Usually readers drop after reading the middle of the book. If you want them to read the second half of your book, you need to find a way to hook them.
  50. Inspiration is not linear. It’s OK to stop writing for a couple of hours.
  51. Motivation is not linear. It’s OK to stop writing for a couple of weeks.
  52. Do not bury the lead.
  53. Be open to critics - even when they hurt your ego.
  54. The more you write, the more you like it.
  55. It’s safe to assume that every developer can read JavaScript.
  56. It’s a great feeling to mention the work of other authors.
  57. You should make sure that each and every code snippet - that appears in your book - runs as expected.
  58. Invoking “it’s so obvious I don’t need to explain it” is not an acceptable argument.
  59. Writing your teaching materials as a dialogue between an imaginary expert and a imaginary novice is a very useful process in order to figure out what questions your materials might raise in your reader’s mind.
  60. Sometimes the questions that an imaginary novice would ask about the stuff you teach would be tough. Don’t ignore them. It’s an opportunity to make your book better.
  61. Rewriting a chapter from scratch because you forgot to save your work could be a blessing as it might lead to a material of higher quality.
  62. Writing in a coffee shop makes me feel as an author from a movie, but in fact I am more productive at home.
  63. Writing a preface - after the whole manuscript is ready - is really fun!
  64. Include at least 2 or 3 diagrams in every chapter. It makes the material more fun to read and easier to grasp.
  65. Draw your diagrams on a sheet of paper before using a drawing software.
  66. When a section is more difficult to read that the others, let your readers know about it.
  67. Asking a friend or a colleague to read your work in progress is not a productive idea.
  68. When you are blocked in the middle of a chapter, it might be a sign that you need to rethink the chapter.
  69. When you are blocked in the middle of a chapter, it might be a sign that you need to rest and come back later.
  70. Adapting parts of your book to blog posts could be a good idea. But you need to resist the temptation of copy-pasting verbatim.
  71. If feels great when someone with 50K followers tweets about the fun they had reading your book.
  72. Writing an appendix is much easier than writing a chapter.
  73. Throwing away some (good) ideas is sometimes necessary. Not easy but necessary.
  74. Using humour in a technical book is possible. Hopefully, it’s appreciated.
  75. You should write the chapter introduction after all the other parts of the chapter are written.
  76. Working on your book is a good reason to wake up early. Sometimes, before sunrise (even in summer!).
  77. Resist the temptation to impress your readers will cool stuff if you think it might confuse them.
  78. Getting positive feedback - even from people who are easily enthusiastic - feels good.
  79. Writing a hundred things you learned from writing a technical book is not as difficult as it may seem.

A hundred things I learned writing my first technical book “Data-Oriented Programming”