In the days of Waterfall Software Development, nobody wanted to pay much attention to Doc Development. I mean, let’s be honest. It was the second-to-last step in the whole process, and pretty much the least glamorous. Although documentation had the potential to occur at any point in the product life cycle, as we have proven with Agile methodology, everyone saved it until near the end, believing it had to be placed until after all of the development, coding and testing was complete, but until before packaging was ready.

We now know that Doc is part of the system, an integral one at that, and yet sometimes it is still the redhead in the room, not getting its due unless it steps up with its fiery temper, begging for the attention it deserves. We know that in some very successful organizations, Documentation gets a well-earned 20-40% of total development effort, while in other organizations, it falls by the wayside, and that lack of effort shows. A perfect example is any company (and there are many) who believe that good technical documentation can be cut in the budget, because support can handle the issues, only to discover that one call to support costs far more than creating good documentation in the first place. Content Strategy 101 offers some insight on the fallacy of low-cost documentation.

So with today’s evolving documentation practices, we have to work hard to improve that documentation mousetrap. We don’t build manuals any more. We don’t ship CDs with pages and pages of tiny-print leaflets of unreadable instructions, so what are some ways to make our ever-evolving documentation relevant?

I suggest that there are a top 5.

Of course there are more like a top 100, but if I put them all here, I will have blogged myself out of a job and I’ll be the irrelevant one, so stay tuned for future blog posts with other super-engaging titles like “Top 5 ways to Test Your Doc!” and “Coordinating Internal Systems!” you get the gist.

For now…

#1

Give User Examples

In Online Documentation, unlike print matter, there is room for Use-Case. Scenario-Based Documentation is popular now, so learn to make it your friend. The SBC is an online user’s friend. Embrace the SBC.

Examples are a superior way for end users to see and experience concepts that are difficult and new. An end user learning new software can experience the software much more easily with a walk-through than with just a third-person explanation.

Switch to second person and allow for a full flow. For example, “When you click on the water icon, you see the mermaid swim across the screen.”

#2

Use Diagrams and Images if Possible

This seems like everyone already knows it, and yet they don’t. OR, if they know it they are not doing it. When the internet was young, everyone was slapping pictures on everything. All of a sudden, we are back to wordiness. I’m a fan of “a picture is worth a thousand words.” Explain a process with a picture, will ya? Not everything needs a photo, but a process sure needs a diagram. If you can minimize the complexity of your documentation by offering a table, do it. Or if you can make it a bulleted list, get on that.

#3

Assume Nothing

You may not know your audience, but presume that they know even less than you do. If you think that the average user is pretty well-versed in computer skills, and you want clutter-free doc, at least take a moment to offer a hyperlink to a basic skills set in an appendix for those who know pretty much zero. Change your mindset to that of a brand-new user who has never seen this stuff. Fully document the process from beginning to end, and then go back and follow your process.

#4

Anticipate Difficulty

Try to break your stuff. You have QA testers who have tried to find issues with the software, so you should try to find issues with your documentation. If the software you are writing for has defects (end users call them bugs) you’ll need to document workarounds for those, providing useful ways to save your users calls to the help desk or support, and proving yourself to be a very useful doc writer. This is a tender spot to be in with developers and testers, but your relationship here counts.

If you are working in an Agile environment, (most of us are these days) you can usually test as you go. You’ll get smaller chunks of doc to try out, in smaller increments, which is nice. Find the zones where your doc is unclear, or could be clearer, and prop it up.

#5

Explore New Technologies

Hey, Documentation is expensive even when it is done correctly, implemented flawlessly and delivered on time and on budget. Doc departments cost money, and we are not the primary product. Is it any wonder doc departments are often trying to justify our very existence?

New technologies will perpetually be the key to creating more effective documentation that is less expensive to develop. New tools are opportunities to reduce time and the cost of the whole process. Look into text-to-speech. Look into better visual editors. Check out the latest in fill-in boxes, component editors, macro checkers – the whole shebang. You will cast aside 90%, but you will find some of them are magical. Remember the little paperclip that sounded like it was tapping on your screen?  Annoying, yes, but nifty nonetheless. Remember the first time you opened Power Point?

Holy cow! Remember the first time you checked out GeoCities?   Now think about the first time you edited in Adobe. Or edited your content into 140 characters.

Check out all of the ways to document.

Myriad. Seriously. Mousetraps upon mousetraps.

And the mousetraps are getting better. The mice are smarter. But the mousetrap builders are pretty smart, too, and we are acquiring better ways to go about it. So don’t move the cheese, just build a better trap. Follow the documentation, and you will have all you need to get the job done right.