100 things I learned writing my first technical book.

Tags: programming
Published: 2021-12-21 04:24:09

<li>Writing a technical book is much harder than writing blog posts.</li>
  <li>Writing a blog post is like running a sprint while writing a book is like running a marathon.</li>
  <li>Writing my first technical book without a publisher would have been a MISSION: IMPOSSIBLE!</li>
  <li>Each piece of the book content must be clear and interesting. Each part, each chapter, each section, each paragraph, each sentence.</li>
  <li>“Clear” is more important that “interesting”. If something is not clear to your reader, it cannot be interesting for for them.</li>
  <li>A possible way to make things clear is go from concrete to abstract.</li>
  <li>A possible way to make things interesting is to teach the material as a story with fiction characters and a bit of drama.</li>
  <li>The “why” is more important than the “what”.</li>
  <li>The “what” is more important than the “how”.</li>
  <li>An average writer makes the reader think the author is smart. A good writer makes the reader think the reader is smart.</li>
  <li>A technical book is written for MQRs (Minimal Qualified Readers).</li>
  <li>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.</li>
  <li>It’s hard to figure out what are the qualifications of your MQRs (Minimal Qualified Readers).</li>
  <li>Checking book sales could be addictive.</li>
  <li>Making a good Table of Contents is crucial as it is the first part of the book potential readers will encounter.</li>
  <li>Making a good Table of Contents is hard as you need to figure out what you really want to talk about.</li>
  <li>The Table of Contents might evolve a bit as you write your book.</li>
  <li>You should resist the temptation to write the first chapter before the Table of Contents is ready.</li>
  <li>It’s not necessary to write chapters in order. But it’s easier.</li>
  <li>Never assume that your readers will read the next chapter only because they have enjoyed the previous chapter.</li>
  <li>You should always convince your readers why what you are teaching is important and relevant for them.</li>
  <li>Before writing a chapter, you should formulate to yourself what is the main objective of the chapter.</li>
  <li>If a chapter has two main objectives, it’s a sign that you should split it into two chapters.</li>
  <li>A chapter should be treated like a piece of software. You should resist the temptation of writing the chapter contents without a plan.</li>
  <li>A possible way to make things interesting is to use concrete examples.</li>
  <li>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.</li>
  <li>Do not hesitate to highlight sentences that convey an important message.</li>
  <li>It’s OK to engage in writing a technical book without mastering every topic you want to cover in your book.</li>
  <li>Writing technical book involves a descent amount of research even if you consider yourself as an expert in the field.</li>
  <li>Finding attractive but accurate titles to book chapters is an art.</li>
  <li>You can learn a lot from a failed attempt to write a book, provided that you put your ago aside.</li>
  <li>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.</li>
  <li>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.</li>
  <li>Writing a technical book takes between a year and two.</li>
  <li>Don’t rush! Enjoy the journey…</li>
  <li>It makes lot of sense to use a source control software for your manuscript.</li>
  <li>AsciiDoc rocks!</li>
  <li>PlantUML rocks!</li>
  <li>NeoVim rocks!</li>
  <li>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).</li>
  <li>People on Reddit could feel hurt by opinions that take them out of their comfort zone.</li>
  <li>On Reddit, when people feel hurt, they could become violent.</li>
  <li>Being mentored by an experienced writer is a blessing.</li>
  <li>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!</li>
  <li>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.</li>
  <li>You should make sure your readers will never frown while reading your book.</li>
  <li>A project manager that pays attention to the details is important.</li>
  <li>Your publisher is your partner.</li>
  <li>You could make more dollars per copy by self-publishing but you’d probably sell much less copies.</li>
  <li>Asking early feedback from external reviewers is a great source of improvement.</li>
  <li>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.</li>
  <li>Finding a good book title is hard.</li>
  <li>Finding a good book subtitle is even harder.</li>
  <li>You need to be very careful not to hurt the sensitivity of any of your readers.</li>
  <li>Having your book featured on HackerNews home page do not mean selling lots of copies.</li>
  <li>Twitter is a great medium to share ideas from your book.</li>
  <li>Writing a book could sometimes take you to flow.</li>
  <li>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.</li>
  <li>It’s hard to find your voice.</li>
  <li>Once you have found the your voice, the writing flows much better.</li>
  <li>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.</li>
  <li>A possible way to hook your readers is to tell a story.</li>
  <li>Inspiration is not linear. It’s OK to stop writing for a couple of hours.</li>
  <li>Motivation is not linear. It’s OK to stop writing for a couple of weeks.</li>
  <li>Be open to critics - even when they hurt your ego.</li>
  <li>The more you write, the more you like it.</li>
  <li>It’s safe to assume that every developer can read JavaScript.</li>
  <li>It’s a great feeling to mention the work of other authors.</li>
  <li>You should make sure that each and every code snippet - that appears in your book - runs as expected.</li>
  <li>Invoking “it’s so obvious I don’t need to explain it” is not an acceptable argument.</li>
  <li>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.</li>
  <li>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.</li>
  <li>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.</li>
  <li>Writing in a coffee shop makes me feel like a famous author, but in fact I am much more productive at home.</li>
  <li>Writing a preface - after the whole manuscript is ready - is really a pleasure!</li>
  <li>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.</li>
  <li>Resist the temptation to impress your readers with “cool stuff” if you think it might confuse them.</li>
  <li>Working on your book is a good reason to wake up early. Sometimes, before sunrise (even in summer!).</li>
  <li>Include at least 2 or 3 diagrams in every chapter. It makes the material fun to read and easier to grasp.</li>
  <li>Draw your diagrams on a sheet of paper before using a drawing software.</li>
  <li>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.</li>
  <li>Mind maps are a great visualization tool. Use them smartly.</li>
  <li>When a section is more difficult to read that the others, let your readers know about it.</li>
  <li>When a section is more difficult to read that the others, make it skippable.</li>
  <li>It’s OK - from times to times - to copy-paste a diagram in order to save from your readers the need to flip back.</li>
  <li>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.</li>
  <li>Brainstorming with a friend or a colleague about a difficulty you encounter might be a productive idea.</li>
  <li>Throwing away some (good) ideas is sometimes necessary. Not easy but necessary.</li>
  <li>When you are blocked in the middle of a chapter, it might be a sign that you need to rethink the chapter.</li>
  <li>When you are blocked in the middle of a chapter, it might be a sign that you need to rest and come back later.</li>
  <li>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.</li>
  <li>If feels great when someone with lots of followers tweets about the fun they had reading your book.</li>
  <li>Don’t worry if your English is not perfect. Your manuscript will be proofread later.</li>
  <li>“Not being an native English speaker” is not an excuse for your lack of clarity.</li>
  <li>Writing an appendix is much easier than writing a chapter.</li>
  <li>Using humour in a technical book is possible. Hopefully, it’s well appreciated.</li>
  <li>You should write the chapter introduction after all the other parts of the chapter are written.</li>
  <li>Getting positive feedback - even from people who are easily enthusiastic - feels good.</li>
  <li>Front matter is the last part an author writes.</li>
  <li>Writing a hundred things you learned from writing a technical book is not as difficult as it may seem.</li>
</ol>