I'm Matthew Setter. I'm an experienced software engineer and a security researcher. I’ve been developing software since 2000 and I started this blog to help you write simpler, cleaner, and more secure software, with less effort.
Technical Writing - Is It A Worthy Role?writing December 17th, 2014
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 software development most of the limelight usually goes to the developers, contributors, and project maintainers. But are other tasks — especially documentation — any less worthy? No! Today I’ll show you why.
Before we get in too deep, I’m not saying that the developers, contributors and maintainers don’t do an essential, often times thankless, job.
They do. Most do it with grace, patience, and without seeking praise, fame, or reward for it.
Often times, just seeing the project develop and succeed, over time, is enough for them. But direct code contributions aren’t the only way to contribute to a project.
There is another task, one not often given the level of distinction attributed to code — it’s technical documentation. Yes, I’m biased about technical documentation; it’s something that I do a lot of, really enjoy, and something that I find truly satisfying.
But it’s also a very worthy, and often times necessary, part of any software development project. Here’s a few reasons why:
- Documentation makes projects accessible to a wider audience
- Not everyone will read the code and tests to learn how a project works
- People learn in different ways
- Code isn’t always clearly written, or self-documenting
- Reading the code won’t give you the background information on a project, such as:
- The reasons why decisions were made
- The reasons why some design choices were made in preference to others
- The constraints on the developers’ time, resources, and budgets which led to decisions, complex logic
Whilst some developers may not need this kind of information, and a lot of the time you can work through a codebase without it, often times this background information can help you join the pieces together faster, forming a deeper appreciation of the project, quicker than solely reading code and tests.
Have You Considered Being a Technical Writer?
There’s an old, flawed, adage which goes something like this:
Those who can, do; those who can’t teach
This is pure garbage! Some of the people who I’ve learned the most from over the years, have also been some of the most experienced.
To teach a topic, to truly teach a topic, you really have to know your subject matter well. I’m not saying every teacher does; but the good ones, especially the great ones, do!
Say what you will, but only when you truly understand a topic, can you teach it; because teaching isn’t just about relating the mechanics of how a library, an application, or a service was constructed.
This isn’t teaching, this is just stating facts, figures and peripheral information. Teaching is truly communicating in the language of the student, not of the teacher.
Given that, you have to know your subject matter so well that you can adjust your approach to suit your audience; and not expect them to adjust their thinking to suit you.
How Do You Get Started?
If you’re keen to get started, now’s a perfect time to begin. You don’t need to ask anyone’s permission to do so; I know I didn’t when I started blogging about Zend Framework 2.
The best thing about it is that it’s so easy to begin. If there’s a project which you love, use regularly, feel that it’s in some way lacking in documentation, get in and lend a hand.
Here’s 8 suggestions to get you started:
- Contribute to the official documentation
- Translate the official documentation in to your mother tongue
- Add meaningful comments and questions to the official documentation when you feel something isn’t clarified fully, didn’t go far enough, or when it’s incorrect
- Start a blog about it
- Start a screencast about it
- Tweet tips, ideas, links, and resources about it
- Become an unofficial evangelist or advocate for the project
- Help out on forums with clear, concise, and constructive input
If you’re a seasoned veteran with over 20 years experience across a range of languages; if you’re just starting out in your software development career; if you’re a project maintainer, or anywhere in between these roles, now is a perfect time to start.
You don’t need much, just the willingness to communicate what you know, to keep on learning, and to become ever more articulate. Everything else you can learn. Don’t see it as a lesser task; it’s every bit as worthy and as interesting as direct code contributions.
Join the Email List
If you enjoyed this post, why not join the email list and get all future posts straight to your inbox? In addition, you'll get background information, extra research, and other content that's only available on the list. I promise I'll NEVER spam you. And you can unsubscribe at any time.