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? 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.

A few examples are Doc Searls at Linux Magazine and Sir Tim Berners Lee, created of the World Wide Web. If you believe that only juniors teach, it’s time to adjust that perspective.

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:

1. Contribute to the official documentation
2. Translate the official documentation in to your mother tongue
3. 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
4. Start a blog about it
5. Start a screencast about it
6. Tweet tips, ideas, links, and resources about it
7. Become an unofficial evangelist or advocate for the project
8. Help out on forums with clear, concise, and constructive input

Wrapping Up

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.

image copyright © JD Hancock