What does it take to be a Technical Author?

How we perceive those that have authored technical books is interesting. The opportunities for anyone to publish content are never better. Anyone can blog; all you need is an email address and access to the internet. Produce enough related content, and you could self-publish a book easily through a platform, even one as big as Amazon. So why do we perceive those that have published books, particularly those who have their content in physical print, differently? Are our assumptions about authors and their abilities correct? Rather than tell you the answer, let me share a view of what it takes to become an author, and you can make up your mind.

To give a little background, I started my career as a developer and, with experience, moved into a technical architecture role. I have co-written two books and a third as a solo project. Much of this article is drawn from both personal experience and insights from friends who have authored books.

Commitment of time

It may seem obvious to say this, but writing a book will take time. A lot of time. While I haven’t kept a record of the time spent on book projects, I can confidently say that my last project took more than 400 hours of work based on my working patterns. If you look at it as 1 hour per page, it doesn’t seem too difficult. This is obviously over a period that an average book can expect to take 9-15 months, but some titles take longer. Remember, this is all time on top of your day job and doesn’t account for the time reflecting on how you might want to approach each chapter, the details, and the insights you want to communicate.

There is no beating around the bush; while a technical bestseller will make a bit of money, it won’t compare to the income of an experienced developer. If personal income as a direct return on your investment of effort is your motivator, then being an author isn’t something I’d recommend. That said, there are other less tangible benefits, but we’ll come to those later.

Belief in your subject

You will need to believe in the idea or technology you’re writing about. That belief doesn’t have to be the level of being zealous or evangelical. I’d say that level of conviction may well be an issue as it risks stopping you from acknowledging when technology has a weakness or isn’t suited to specific scenarios. On the other hand, a lack of belief will make pushing forward harder when things are challenging. Of course, your view risks coming through in your writing and undermines all your effort.

Every nut and bolt?

It may surprise some when I say you don’t need to know every nut and bolt of what you’re writing about at the outset. Still, you need to be reasonably conversant and probably most crucially have a strong understanding of the architecture and how things work. That architectural understanding will help you address the things you don’t entirely know. As was famously said by Donald Rumsfeld, there are unknown unknowns and known unknowns. You can have known unknowns, but in your writing journey, be prepared to embrace and address them if it makes sense to the book. But not only that, if you have known unknowns, it is reasonable to suggest that will be true for others. In addressing those unknowns, you’re increasing the value of the book.

Regarding the unknown unknowns, we can address this challenge by researching your subject as much as possible. What issues are discussed in chat forums? How would you apply the technology in more niche use cases? What conditions would it not make sense to apply your subject matter?  How is the code structured if you can see it? Answering these sorts of questions will translate unknown unknowns into the known unknowns we’re prepared for.

Teach to fish

An old expression goes, “If you give a man a fish, you feed him for a day. If you teach a man to fish, you feed him for a lifetime”. In other words, if you give someone the answer to a problem, they can solve the problem. But explain to someone why something is a problem and how and why a solution works. Then they’ll not only overcome their current obstacle but will have the understanding to avoid or solve related issues in the future. An inherent trait of technical books is for them to age relatively quickly, but the best books are those that, while they may start to date, still have excellent insights into the whys and wherefores and will continue to sell and offer value to readers. Proof of this can be seen in books like Gerald Weinberg’s Psychology of Computer Programming – written in 1971; while its explanations are dated (discussions of punch cards, etc.), the underlying themes are still valid today. If the feedback I’ve received is something to go by, sharing not just answers but why answers work is what engages.

It’s all in the code

The well-worn argument against documentation has been that good code will be self-documenting. But even quality code can’t express how thousands or hundreds of thousands of lines of code fit together; even if you could review all the code, it would feel like the lines from the song “The Book Of Love” – “The book of love is long and boring, No one can lift the damn thing.” As an effective author, it is much about condensing all that ‘self-documenting code’ into enough information that allows the reader to use the technology and, importantly, help them understand how to best use it and avoid common pitfalls. But not only are we trying to condense the documentation, but we are also ideally offering insights and adding value, or as the song puts it, “I love it when you read to me.”

Edit, edit, and edit again

Don’t be afraid to review and edit your writing. Self-reviewing, for many, can be challenging, and it is easy to read what you think you’ve written. So often, it helps to leave what you’ve written and move on to the next thing before revisiting what you have written. A bit of time away from what you’ve written generally makes having a critical eye easier, and seeing the points you missed or feel could be better expressed.  Better still, have the confidence to get someone else to review the writing and give feedback. People that know you are likely to know how to give feedback that will be easier to swallow. Or at least you won’t be prepared to admit they’re right. I wrote one chapter for a book, and it wasn’t up to the mark for one reason or another. Well, it took a colleague to tell me the chapter needed significant work to bring it up to the stand people expect from me. Had I not listened and taken that onboard, the discussion with the publisher and their reviewers would have probably been a lot less comfortable.

Clarity of message

To convey essential details, you need clarity in your thinking to get the points you think are essential. Clarity doesn’t always come immediately, particularly if you’re an intuitive person. If you’re not clear in your mind on something, how will a reader get the clarity they want? This doesn’t mean that if you’re an intuitive person, you’re not going to be a good author. It does mean that you will need the patience to reflect on what you have intuitively understood until you get the clarity to express something clearly. Sometimes the best way is to write a stream of consciousness out and then be willing to write and rewrite until that clarity arrives.  My preference is to reflect or talk things through with colleagues – the conversations over a drink with a back and forth can help cut through to the key point.

It isn’t all words

The saying goes, “a picture is worth a thousand words.” You don’t need to be a da Vinci or a Visio guru (to be honest, I hate working with Visio and use PowerPoint). Even hand-drawn illustrations are becoming popular. The Key is that it needs to be enough to help visual learners. If you’re working with a publisher, they may have a graphics team who can help.

The payback

Altruism is a funny thing; some people reject the idea and argue there is always some payback or driver like Richard Hawkins’ “selfish gene.” So, is there a payback for taking on the technical writing challenge? Very much so, but as I indicated, it isn’t directly fiscal. However, there are indirect benefits, which is why you’ll often see independent consultants write. Like being recognized as a key committer to an open-source project, being a published author distinguishes you from the crowd. As an employee or freelancer, that gives you greater credibility, and that credibility, in turn, can help with a range of things – from finding a job to negotiating salary to helping raise the chance of a paper being selected at a conference.

The less tangible benefits are probably more significant, like delivering a large project, seeing it go live, and delivering value. There is a real endorphin hit. Unlike delivering a project, a book is more of an individual effort – certainly, others will help you there. Still, it is essentially solo, so the hit is correspondingly bigger.

What goes around

For me, at least, and I think it is true of others when you read/hear that someone said they have benefited from the book is also greatly rewarding. If you like the ideas of ‘paying it forward’ or ‘what goes around, comes around,’ this response will make a difference.

This would lead me to an appeal to any reader – if you got something beneficial from a book – openly say so. If the book doesn’t live up to your expectations or hopes, rather than being negatively critical, offer your view in a constructive tone like ‘it would help if the book had …’. Such things help the author find the courage to swing at a new title or second edition. Such comments are just so much easier to take onboard and act on.  As the second time around, the idea of writing can be a lot more intimidating as you know what you’re signing up for.

Conclusion

From this, I hope that you’ll see that becoming a technical author isn’t something only reserved for a rare set of talents and being a guru on a particular subject. It is more about the motivation to help and share understanding and insights. Through the journey of becoming a tech author, you’re likely to extend your knowledge that will take you closer to being a subject matter expert.

If we’ve convinced you that you might have what it takes and would like to know more about the practicalities of an authoring project, such as how we have engaged with a publisher and developed an idea into an actual project, then please check out my blog.

Phil Wilkins

Phil Wilkins has over 30 years of experience in the software industry, working in environments as diverse as multinational and niche consultancies, software start-ups, manufacturing, and end-user organizations. Phil focuses on APIs, Integration, and backend development. He works as a Cloud Native Developer Evangelist at Oracle.

Phil (co)authored books on Fluentd and API & Integration development products. He is also a blogger and contributor to tech journals. Phil has presented at conferences physically & virtually around the world.

Software Daily

Software Daily

 
Subscribe to Software Daily, a curated newsletter featuring the best and newest from the software engineering community.