Technical Writing - Is It A Worthy Role?
In software development most of the limelight usually goes to the developers, contributors, and project maintainers. But are other tasks — especially documentation — any less worthy?
Recently I dateed my first book, Zend Framework 2 Foundations and I’m really excited. Not only is it on my
Recently I dateed my first book, Zend Framework 2 Foundations and I’m really excited. Not only is it on my favourite topic, software development, but it’s on my favourite language’s biggest framework, PHP’s Zend Framework 2.
So today, I wanted to start writing up the journey from concept to completed book. Perhaps you’re thinking of writing a book as well, whether personally or for your business.
As the process is so involved, it’s going to take a couple of posts to cover everything. But if you read through the whole series, you’ll be in a much better position than I was, when I started my journey some months ago.
Here, in part one, I want to cover what, to me, is the most important aspect of writing a book:
What problem are you Solving?
Note that I’m not talking about the process of actually writing a book, editing it or proofreading it? You see, at the start (I guess it’s the flaw of a technically trained person), I thought that the important parts were the actual construction of the book.
What’s the right chapter order; what size should the book be; what parts of the framework should I cover and to what level of detail, and so forth.
What I learned through the process is that nothing could be further from the truth. Ok, yes, you do have to write great content and edit it so that it makes sense, is clear to your reader, is technically accurate and so on.
These are important steps, don’t get me wrong. But they’re not the most important ones! The most important one is the one I’ve mentioned above.
This one is critical, because it’s the reason why someone would be motivated to buy your book — it’s the emotional hook.
Get this one wrong and you could have the most technically accurate book in the world, but there’s no compelling reason for someone to buy it.
Get this right and you’ll hook in to a compelling need that the potential buyer is aiming to solve, placing yourself as the solution to that problem.
One of the most successful technical authors I know, Chris Hartjes, aka the Grumpy Programmer, says you need to remember three things:
For me, I was solving the issue of getting started with Zend Framework 2. Whilst the framework has a lot of buzz around it, and is extremely feature rich, it’s seen as not being an easy framework to get started with.
In reality it’s quite easy to get started with, but on the surface of it, it doesn’t come across that way. From experience, it’s even one of the most powerful PHP frameworks around, but to get to that power and simplicity, you have to dig.
The book solves the problem of getting started, by helping overcome the documentation hurdle. What I mean is that whilst there is quite an amount of documentation for Zend Framework 2 it’s not as comprehensive as it needs to be; to the point that it’s one of the most cited detractions.
Me, I love using the framework, to the extent that I blog regularly about it. But despite that, I (still) feel that the documentation does’t go far enough; especially in contrast with other frameworks, such as Laravel and FuelPHP.
So this is the problem my book solves. To identify a problem isn’t hard. Often it’s as simple as having a proverbial itch to scratch. To identify the need, here is a series of questions to ask:
In the next instalment in this series, we look at the second key question: Who is Your Target Market. Till then, what’s your experience with writing a book? Have you clearly identified the problem which your book solves?
In software development most of the limelight usually goes to the developers, contributors, and project maintainers. But are other tasks — especially documentation — any less worthy?
In this post you’ll learn what it takes to write a great tech blog post — in 5 simple steps.
I’ve been a software developer for close on 14 years now. But for only a precious few moments during those
Looking for an application giving you the ability to organize your writing like sheets of paper, with the power of a web-based app? If so, I’ve got the answer!
Please consider buying me a coffee. It really helps me to keep producing new tutorials.
Join the discussion
comments powered by Disqus