Challenges in writing a programming book

Have you ever thought about writing a book about software engineering?

I have. I thought about this idea of a book that would teach you React, Angular, and Vue all at once for years and years.

The idea started as a simple blog post series and, as I learned more about each respective framework, I realized that wouldn't cut it.

Finally something cracked. I had been writing blog posts both professionally and not for a while. I had amassed 50 blog posts in my repertoire and thought "How hard could it be?"

This started my journey to write "The Framework Field Guide", a trilogy of programming books that I'm making free for the general public.

While I've only finished one of the books thus far, I want to share with you my learnings around this time.

Writing a book is hard

It took me a little over two years to:

• Start writing a book

• Realize it was getting too long, even in rough sketches of headings

• Re-organize existing content and outline enough rough content to fill a trilogy of books

• Develop a high-performance custom-designed marketing site
  

• Redesign and rewrite an entire blogging platform to host the book's contents on

• Write the first book

  • 95K words
  • 16 chapters

  

• Create code samples & embeds for every code block in the book

  • 25K lines of code

  

• Do grammar and spelling edits to the book's contents

All while maintaining my day job's duties of leading a software engineering team.

What's more; book sales are rough. While I'm not charging for my content, I've regularly heard from other authors that writing content is challenging to break even with your time spent. Consider your salary, now consider how much time it'd take to do everything I just listed. Are you willing to take home (potentially) a lot less than you might by doing consulting?

Moreover, how are you going to price things? Price too low (like I have) and people tend to devalue your work (even subconsciously). Price too high and your work is inaccessible to many.

All-in-all, you have to:

• Be willing to write for yourself
• Stay resilient and know that the outcome will be immensely rewarding

Developers glance, not read

This article is going to lose a lot of readers. Why? Well, during my past five years writing for developers I've learned that the content that has the best engagement has:

• A shorter in length
• Content broken up by images
• Bolded and italicized formatting
• Lists to break up formatting even further
• The article filled with code

You generally want your article to more like this:

And less like this:

Notice how boring this screenshot looks? Nobody's reading all of that. Break it up with formatting, images, emoji - anything to spice it up!

Keep your headings clearly named

As I mentioned previously, most developers will only glance at your articles. If your headings aren't representative of what they'll be learning underneath them, they'll likely gloss over their content.

It may be tempting to have fun headings like this:

Try instead to be more explicit with what's being talked about:

Code will be copy+pasted

Assume your article or book includes JavaScript code that demonstrates some broken code like so:

const test = = 123;

This might be an obvious error to us, it might not be so clear for a newcomer developer.

Instead of this code block on its own, try to annotate it using comments inside the code block itself:

// This is broken code, remove the second `=` to fix it
const test = = 123;

Lean into copy+pasted code; it's how many developers will learn. Force them to tweak code themselves to see the results they want - it encourages learning and interactivity!

Developers seem to prefer video content

You might ask yourself on your journey if a pre-recorded video content is worthwhile making. While editing can be lengthy and recording can be intimidating, the return on investment (ROI) for video content appears to be higher for developers in my experience.

Compare and contrast a reasonably successful article of mine:

To the meteoric rise of, say, Theo over on YouTube:

For what it's worth, I don't recommend investing very heavily in live-streaming on Twitch or YouTube. I've written about this before, but my 1K+ hours on the platform has yielded minimal ROI.

Conclusion

Making content of any kind can be a grueling task. If you choose to write a book about software engineering, you can expect to pour hours and hours into the writing process.

But if you pull it off, you'll have an improved resume, bragging rights, and have likely helped someone along the way learn valuable skills in their career.

There's more to share, which I'll include in a future series, but that's all for now.

And hey, if you wouldn't mind - I'd love you to take a look and share my book, "The Framework Field Guide":

It's free and teaches multiple frameworks at once. Thanks a bunch!