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