This is the fourth fight in my series The Seven Righteous Fights. For an introduction, see The Seven Righteous Fights: Overview.
I’m a technical writer, so you knew I’d get here.
Documentation is not a secret!
I often deal with product and business people who want to put the documentation behind a login. They want to know who’s reading, they want to harvest sales contacts, that information is valuable to them.
But from the user point of view, having to log in is an extra step, one that not everyone requires. If a sysadmin is looking for information on your product, and they can’t get it without signing up to be pestered by sales calls, they may look at another product first.
On the other hand, if your documentation is clear and helpful and easy to get at, then they are half persuaded right away.
User documents are not the problem
A lot of user docs are actually straightforward to retrofit. That’s what I do for a living.
I come in and create all the first set of documents for a product, and the structure to sustain it.
What’s not easy is:
Developer onboarding
Imagine if you had a tax that took 10 developer hours a week for a month.
I’m here to tell you do, you just aren’t aware you’re paying it. It’s absolutely vital for you to add developers as fast as you can, but it’s also pretty darn important that you not bog down the existing developers who are running as fast as they can.
Taking the time to write a development onboarding document is going to save you a lot of wasted coaching time, and means that when your new devs do have questions, they’re interesting and relevant, not repetitive.
Production and build scripts
This is probably not anything you’d use a tech writer for, but you should think about storing that information somewhere safe. It is pretty devastating for a company’s ability to produce builds consistently if the only person who knows how to do it is gone or sick or has taken a new job.
When you hire a build or production engineer, be sure you get some writing samples from them of how they have made it possible to work without their physical presence.
This is the worst place in the company to keep someone cagey and secretive.
Release Notes
If sysadmins and installers and application owners read nothing else, they read the release notes. It’s vital to know if you are going to install something incompatible, or if a release fixes your problems.
People care deeply about release notes and shoving them into an unloved readme is no way to treat the people actually touching your product and setting it up for others.
Summary
Documentation, it’s not just for professionals to write, and it’s not just for end-users to read. Build in that assumption from the start.
This blog post is part 4 of my Seven Fights series. You can hear me give this talk at SpringOne Platform (August 1-4) or Abstractions (August 18-20).