Things I learned writing my first technical book

1. Writing a technical book is much harder than writing blog posts.
2. Writing a blog post is like running a sprint while writing a book is like running a marathon.
3. Writing my first technical book without a publisher would have been a MISSION: IMPOSSIBLE!
4. Each piece of the book content must be clear and interesting. Each part, each chapter, each section, each paragraph, each sentence.
5. “Clear” is more important that “interesting”. If something is not clear to your reader, it cannot be interesting for for them.
6. A possible way to make things clear is go from concrete to abstract.
7. A possible way to make things interesting is to teach the material as a story with fiction characters and a bit of drama.
8. The “why” is more important than the “what”.
9. The “what” is more important than the “how”.
10. An average writer makes the reader think the author is smart. A good writer makes the reader think the reader is smart.
11. A technical book is written for MQRs (Minimal Qualified Readers).
12. Figuring out what are the qualifications of your MQRs (Minimal Qualified Readers) is important as it allows you to assume what knowledge your readers already have.
13. It’s hard to figure out what are the qualifications of your MQRs (Minimal Qualified Readers).
14. Checking book sales could be addictive.
15. Making a good Table of Contents is crucial as it is the first part of the book potential readers will encounter.
16. Making a good Table of Contents is hard as you need to figure out what you really want to talk about.
17. The Table of Contents might evolve a bit as you write your book.
18. You should resist the temptation to write the first chapter before the Table of Contents is ready.
19. It’s not necessary to write chapters in order. But it’s easier.
20. Never assume that your readers will read the next chapter only because they have enjoyed the previous chapter.
21. You should always convince your readers why what you are teaching is important and relevant for them.
22. Before writing a chapter, you should formulate to yourself what is the main objective of the chapter.
23. If a chapter has two main objectives, it’s a sign that you should split it into two chapters.
24. A chapter should be treated like a piece of software. You should resist the temptation of writing the chapter contents without a plan.
25. A possible way to make things interesting is to use concrete examples.
26. A possible way to make things clear inside a chapter is to start with the easy stuff and increase the level of difficulty as the chapter goes.
27. Do not hesitate to highlight sentences that convey an important message.
28. It’s OK to engage in writing a technical book without mastering every topic you want to cover in your book.
29. Writing technical book involves a descent amount of research even if you consider yourself as an expert in the field.
30. Finding attractive but accurate titles to book chapters is an art.
31. You can learn a lot from a failed attempt to write a book, provided that you put your ago aside.
32. 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.
33. It’s possible to write a technical book while keeping your day job as a programmer, provided that you are willing to wake up early or sleep late.
34. Writing a technical book takes between a year and two.
35. Don’t rush! Enjoy the journey…
36. It makes lot of sense to use a source control software for your manuscript.
37. AsciiDoc rocks!
38. PlantUML rocks!
39. NeoVim rocks!
40. Using a tool - like PlantUML - that generates diagrams from text makes it easy to refactor multiple diagrams at once (e.g rename a label, change a color).
41. People on Reddit could feel hurt by opinions that take them out of their comfort zone.
42. On Reddit, when people feel hurt, they could become violent.
43. Being mentored by an experienced writer is a blessing.
44. If you are lucky enough to be mentored by an experienced writer, ask them to be hard with you. That’s how you are going to improve your book!
45. A good technical reviewer is a representative of your MQRs (Minimal Qualified Readers). They can tell you upfront is something is going to be unclear to your readers.
46. You should make sure your readers will never frown while reading your book.
47. A project manager that pays attention to the details is important.
48. Your publisher is your partner.
49. You could make more dollars per copy by self-publishing but you’d probably sell much less copies.
50. Asking early feedback from external reviewers is a great source of improvement.
51. 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.
52. Finding a good book title is hard.
53. Finding a good book subtitle is even harder.
54. You need to be very careful not to hurt the sensitivity of any of your readers.
55. Having your book featured on HackerNews home page do not mean selling lots of copies.
56. Twitter is a great medium to share ideas from your book.
57. Writing a book could sometimes take you to flow.
58. 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.
59. It’s hard to find your voice.
60. Once you have found the your voice, the writing flows much better.
61. Usually readers stop reading 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.
62. A possible way to hook your readers is to tell a story.
63. Inspiration is not linear. It’s OK to stop writing for a couple of hours.
64. Motivation is not linear. It’s OK to stop writing for a couple of weeks.
65. Be open to critics - even when they hurt your ego.
66. The more you write, the more you like it.
67. It’s safe to assume that every developer can read JavaScript.
68. It’s a great feeling to mention the work of other authors.
69. You should make sure that each and every code snippet - that appears in your book - runs as expected.
70. Invoking “it’s so obvious I don’t need to explain it” is not an acceptable argument.
71. 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.
72. 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.
73. Rewriting a chapter from scratch because you forgot to save your work could be a blessing as writing from scratch might lead to a material of higher quality.
74. Writing in a coffee shop makes me feel like a famous author, but in fact I am much more productive at home.
75. Writing a preface - after the whole manuscript is ready - is really a pleasure!
76. You should think about the way your contents is going to appear on the paper. Use headlines, highlights, call outs and diagrams to make sure it doesn’t look boring.
77. Resist the temptation to impress your readers with “cool stuff” if you think it might confuse them.
78. Working on your book is a good reason to wake up early. Sometimes, before sunrise (even in summer!).
79. Include at least 2 or 3 diagrams in every chapter. It makes the material fun to read and easier to grasp.
80. Draw your diagrams on a sheet of paper before using a drawing software.
81. It’s OK to use colors in diagrams for the online version of the book. But remember that the print version of the book will be not be in color.
82. Mind maps are a great visualization tool. Use them smartly.
83. When a section is more difficult to read that the others, let your readers know about it.
84. When a section is more difficult to read that the others, make it skippable.
85. It’s OK - from times to times - to copy-paste a diagram in order to save from your readers the need to flip back.
86. Asking a friend or a colleague to read your work in progress is not a productive idea. The best feedback come from people you don’t know.
87. Brainstorming with a friend or a colleague about a difficulty you encounter might be a productive idea.
88. Throwing away some (good) ideas is sometimes necessary. Not easy but necessary.
89. When you are blocked in the middle of a chapter, it might be a sign that you need to rethink the chapter.
90. When you are blocked in the middle of a chapter, it might be a sign that you need to rest and come back later.
91. Adapting parts of your book to blog posts could be a good idea. But you need to resist the temptation of copy-pasting verbatim as the blog posts will be without the context of the book.
92. If feels great when someone with lots of followers tweets about the fun they had reading your book.
93. Don’t worry if your English is not perfect. Your manuscript will be proofread later.
94. “Not being an native English speaker” is not an excuse for your lack of clarity.
95. Writing an appendix is much easier than writing a chapter.
96. Using humour in a technical book is possible. Hopefully, it’s well appreciated.
97. You should write the chapter introduction after all the other parts of the chapter are written.
98. Getting positive feedback - even from people who are easily enthusiastic - feels good.
99. Front matter is the last part an author writes.
100. Writing a hundred things you learned from writing a technical book is not as difficult as it may seem.

Subscribe to Yehonathan Sharvit newsletter

Get the latest and greatest from Yehonathan Sharvit delivered straight to your inbox every week.

from Hacker News https://ift.tt/3e6xU2H