I’ve had a few discussions recently about the value a technical writer can bring to an organization. Unsurprisingly, given what I do for a living, the discussions have centered around the value a very technical writer brings to the table.
Clearly, it’s time to write some of this down.
In most companies, writers are usually a fairly low priority—right until they become a very urgent requirement, that is. At that point, you and the writer you find (or the engineer you re-task) are already in a bind. It’s unfortunate, but hardly surprising, that most engineers and project managers have never had a writer involved from the beginning of a project. It’s never too late to do the right thing, though, and doing it earlier keeps everyone happier.
What is involved in really technical writing surprises a lot of people. I work right in your code. I document APIs, clean up (and in a lot of cases, write from scratch) the comments in production code, and produce documentation and deliver training based on a detailed understanding of what’s going on.
It should come as no surprise, then, that a happy client had this to say recently:
I found Alex to be fantastic to work with due to his ability to grasp the technical issues around our project.
I still blush a bit when I read the “fantastic” part. In that particular instance, I had translated a whiteboard full of drawings into a fully-illustrated software design document. It took me a few days to do it, and saved him a lot more time than that.
When your documentation is good, and is packaged in formats that work well for you, you get some serious long-term benefits. Here are a few:
- Save time and money: help new developers get ramped-up and productive. Recently, a newly-hired engineer was so delighted with the level of documentation in the code, he emailed me just to say so: “[Redacted] tells me all the comments in this code are your fault. I am weeks ahead now. Thanks!!!”
- Get a team started on the next version of a project. When a client started a new project based on another I’d worked on, the engineering manager told me that “The old APIs are so well-documented, we’re halfway to beta on this already.”
- Reduce your support and training costs when you roll out an API or platform to partners. Good reference and training materials are always appreciated.
While I’m at it, I’ll edit your content, both internal and public-facing. I don’t accept exclusively-editorial contracts, because I prefer to write, but I’m happy to thoroughly and professionally edit anything an existing client might need.
There are lots of reasons to get me involved in a project as early as possible, most of which stem from the fact that I’m really good at translation. Among other things, I translate from geeks to executives and back again, code into comments, comments into documentation and training classes, napkin drawings and casual conversations into specifications.
And of course there are lots of ways to structure that involvement: project-based contracts, retainers, time-and-materials contracts, and others, even full-time offers. Get in touch and let’s get things rolling.