Setting up a New Tech Pubs Department: Deliverables
So, you joined a startup (or somehow inherited the Documentation function at your place of work). You realize that professional, consistent, high-quality documentation can be a significant part of making your customers successful, so you sit down to build the department.
What kinds of procedures do you need? What kinds of employees should you hire? What kinds of deliverables will you offer?
I covered hiring writers in a previous post so we’ll tackle deliverables now and save procedures for the next time.
Delivering Success
Unless the company is very small and in its very early stages, you likely already have some sort of documentation or at least expectations about what documentation needs to be delivered. But now is a good time to take a census — what you have now vs. what you need.
As an example, in my latest job, I came on board to take documentation to the professional level. We already had:
- Release Notes
- User Guides
And that’s about it! Maybe you’ll have more in your place, things like dedicated installation/upgrade/maintenance manuals. etc.
Right off the bat, I noticed that the User Guide was “overloaded”, meaning all of the documentation (except for the Release Notes) was crammed into a single monolithic document.
That approach can work, but only if you have a whip-smart navigation and search layer on top. If you just rely on the left-hand navigation bar/TOC to get customers to where they need to go, you may be surprised at how poorly that works. Remember, many/most of your readers will be coming into the documentation directly from a web search. So have a way for them to quickly find their bearings. I’m a big fan of a giant “NEW? START HERE!” link.
Remember that audiences aren’t always homogeneous. In other words, you may have some users who only perform “administration” of your product, while others are “end users” or “power users”. A one-size-fits-all approach can often be a liability. Again, make the information easy to find. You’ll be seeking a balance between wide (many shallow guides or pages) and narrow (fewer, deeper topics).
Now that you’ve taken a census, you can see what you have and get an idea of what you need.
Next you’ll want to assess the quality of what you have. In my case, yes we had Release Notes, but they were mostly auto-generated via a query against the bug database. They didn’t include much in the way of context or other helpful information (upgrade paths, installation instructions, behavior changes, deprecations, known issues, etc.).
With that done, you should have a grid or matrix of some kind: documentation you want on one axis, and the state/quality/availability on the other.
And so forth.
Setting Priorities
Now that you have your matrix, you can decide what’s important — what to work on first. (Depending on the amount of writing resources you have, you may be able to tackle multiple items simultaneously.)
You may be tempted to fill in the missing items first. Normally that would make sense, especially if you can improve existing documentation later. In our case, we had such intense pressure from customers demanding improved Release Notes that we started there. You mileage, as they say, may vary.
Iterating for Success
And one last thought I’ll leave you with. Documentation is an iterative process. You will literally never “finish” documenting a product (unless development ceases and customers stop using it). If you know this, if you accept this mantra going in, the process becomes much more manageable.
Know that the product will continue to evolve. Plan to continue to improve the documentation. You don’t have to make incredible, huge strides with each release, as long as you’re constantly moving forward, making improvements.
Set those expectations internally and with customers.
Make this a part of your early messaging with the team and customers (if you can reach them, otherwise ask Support/etc. to share that message if/when possible). I have a presentation I like to give, called “Why Tech Pubs?” In it, I mention several times that the plan is to make continual improvement to the documentation. Just like your product (likely) has maintenance releases to refine the product or its features and address bugs, the documentation will have releases. I’d urge you to find a way to separate documentation updates from product updates so you can make changes even more incrementally, in-between releases.
And that’s it for taking inventory:
- Take a census.
- Prioritize.
- Iterate.
Next time: documentation procedures.
