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?
You may have the best platform in the world, providing the world’s greatest security or performance, to a level unmatched by anyone else. But will developers use it?
You may have the best platform in the world, providing the world’s greatest security or performance, to a level unmatched by anyone else. But will developers use it?
If it’s unclear, opaque, or the learning curve’s too steep, your platform will be assigned to the “too hard” basket. Developers will leave in search of one which is clearer, one which involves less work to understand and use. Don’t let this be your platform.
If there’s one thing developers need – it’s documentation. Whilst most of us are intelligent, experienced and engaged people, passionate about our craft, sometimes to a fault, very few of us are geniuses, very few of us can infer what we need from source code alone.
Sometimes the source code is written in such a way that only the original developer can really understand the its intent. From personal experience, here’s a number of reasons why:
The same goes for technology platforms. Now I don’t say this to worry you. If you have a fantastic platform, with outstanding support, you’ve accomplished the majority of the work required.
But don’t let it go to waste by not providing clear (and copious) documentation, so developers can get started quickly, then move on to make the most of it.
You may be wondering, why the focus on developers. Maybe you’re familiar with a quote, often attributed to Francis Xavier, the founder of the Jesuit Order:
Give me the child until he is seven and I’ll give you the man
There’s a lot in that and it makes a lot of sense when you think about it. If developers become accustomed to working with a specific platform, a specific set of tools, a specific way of working, they’ll want to keep working that way (assuming that it truly allows them to be the best they can be).
As they move to different companies over the course of their career, building new platforms and overhauling existing ones, they’ll want to use the tools and platforms they’re already familiar with.
When questions are asked about what platform or tool is the right one to use given a particular situation, they’ll put forwards the ones they know (and like) best.
If a new platform or tool is sought, because of a new client, to speed up an existing application, to refactor a legacy application, naturally they’ll support the ones they know – if for no other reason than they get to keep working on what they love.
So it makes sense that you need to make yours as easy as possible, by providing thorough documentation, so that yours is the one they choose.
Gladly, the answer is simple and comprised of three simple, yet key parts:
Do you provide hosting, caching, email, and logging services. Specifically, what powers those services? Is it Memcached, Postfix, PostgreSQL, Cassandra, MongoDB, MySQL and MariaDB?
With this in mind, are there any peculiarities to accessing these services, which developers should be aware of? How have you made getting up and running simpler, quicker, easier? What key processes or features does your platform provide, which saves time and effort?
It’d be great to go after every developer on the planet, of which there are hundreds of thousands. But to maximise your platform’s value, as Ramit Sethi says, focus on a specific niche. By doing so, you’ll come to be more acutely aware of the way they think, they needs they have, the supplemental technologies which are important to them, and on the list goes.
With these first two steps done, brainstorm a series of posts, which you can add to your blog, which show real, working, usage examples of the various parts of your platform. This can be from the very simple, such as how to roll out framework X, to the more complex, such as how to manage a deployment process.
Over the course of weeks and months, you’ll begin to carve out a place for yourself, with the niche you’ve identified. You’ll begin building a reputation with them as one of their preferred choices; because you understand them so well. I won’t try and tell you that it will come overnight. But given time, focus and dedication, I’m confident you’ll see the results you want.
Granted, it’s one thing to say all this, and another thing to do it. So if you’re keen, but finding it tough going, email me and let’s see what we can do, together, to get it happening for you.
Otherwise, are you already doing this? If so, what’s your return on the investment been like? More than you expected? Less? Somewhere in the middle. Share your experiences in the comments.
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.
Recently I dateed my first book, Zend Framework 2 Foundations and I’m really excited. Not only is it on my
I’ve been a software developer for close on 14 years now. But for only a precious few moments during those
Please consider buying me a coffee. It really helps me to keep producing new tutorials.
Join the discussion
comments powered by Disqus