The three documents you ACTUALLY need first

Because I work as only-writer for so much of my time, I forget that I’m not just a lone technical writer, and I’m not just an indie, but I’m in an odd category beyond that. Because no one who hires me really knows what a technical writer does, interviewing is often turned on its head for me. I do a little research on a company and then walk in and explain to them what the first three documents they need me to write are. It makes me look like a genius, and it has a reasonably high success rate. Also, it stops them from explaining their business model to me. If I haven’t figured out your business model, and you aren’t in stealth mode, the first thing we need to fix is your web presence.

The three documents that people think they need first are: Installation guide, User guide, FAQ.

The three documents that people probably actually need first are: Developer onboarding, Configuration, and Sandbox.

Developer onboarding

By the time people get around to hiring me, they are exploding their hiring, and adding developers as fast as they can find them. You can either hand them a document on setting up their environment (or better yet, a pre-built VM), or you can devote your existing developer’s time to walk them through a process that has a dozen backtracks, and no one gets anything done for a week. I am SO MUCH CHEAPER than manual onboarding, and a document SCALES, unlike the one person who understands how to set up your development environment.

Configuration

Most of the software I’m working with now comes in both hosted and on-premise flavors. Ignore the on-premise for as long as possible, because it’s always a nightmare of idiosyncracy. Instead, drive people to use the hosted solution by offering them the MUCH SIMPLER configuration guide that lets them set things up the way they want without having to build an environment from scratch.

Sandbox

It’s no good telling people how to use something if they have no motivation to learn. The people that you need to talk to if you are in the early stage of going public (publicity, not IPO sense) are not the same people who will be compelled to learn the software because they need it day in and day out. The audience for new products is the decision-makers, who are often far removed from the daily grind and who have no motivation to learn step-by-step. No, they want to play with the product and see what it’s capable of.

If you give them a way to make the experience touchable, real to them, it’s going to mean more than a dozen slides and even hands-off demos would.

 

Heidi Waterhouse

Heidi is a mercenary technical writer and travelling salesperson of better process and product thinking. She loves writing herself out of a job and teaching people to save themselves from future pain.

Upcoming appearances

DevOpsDays Seattle
DevNet Create
GOTO Chicago
Deliver:AgileAlliance
O'Reilly Software Architecture/Velocity
The Lead Developer London