DEV Community 👩‍💻👨‍💻

Cover image for 100 things I learned writing my first technical book.
LordVictor0424
LordVictor0424

Posted on • Updated on

100 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.

  • Top comments (0)

    Find what you were looking for? Join hundreds of thousands of developers on DEV so you can:

    🌚 Enable dark mode
    🔠 Change your default font
    📚 Adjust your experience level to see more relevant content