RSS 
Email 
Twitter
FacebookMinimizing Documentation
November 11th, 2009 | Posted in Technical Writing 12 Comments »
I recently attended an STC chapter presentation on interface design, and the speaker, Grant Skousen, showed us the following graphic.
Simplicity and complexity
We then launched into a discussion about minimalism. I think we all agree that minimalism in user interfaces is an increasing trend, especially with the success of the iPod and iPhone, which are all about simplicity and minimal design.
Grant said every time you add something to an interface, you should take something away. Keeping the interface simple ensures you aren’t crowding out screen real estate. He then quoted Elder M. Russell Ballard, who said:
To innovate does not necessarily mean to expand; very often it means to simplify.
If you just keep adding components to the interface, your core features get diluted, Grant said.
I asked Grant if the same principles of minimalism in interface design also applied to help materials. No doubt you’ve heard some say that you don’t have to document everything.
Grant wasn’t sure if it applied. Minimalism in documentation does have a similar effect as minimalism in design, though. Cutting out the extraneous text, unnecessary diagrams, and edge-case videos reduces content dilution. Your users can focus on the key help material that matters and that you want to be sure they read.
Is less always more? I’m not sure. But if Apple’s minimalistic designs are any indicator of trends, minimalism in documentation is something to pay attention to. Here are five ideas for minimizing documentation:
1. Make the interface simpler.
If you can fix a confusing interface design or workflow, you can reduce the need for excessive instructions. This is the ideal solution to minimizing documentation, but it requires you to get involved in the development process early on, when you’re at the prototype stage. At times you have to present your case like a lawyer, bringing the evidence of user feedback and metrics to persuade project managers and designers to change the prototypes.
2. Make the help context-sensitive.
If you can present the user with help specific to the page or task at hand, this reduces the perceived amount of documentation that the user encounters. This may not reduce how much text you write. In fact, it may increase it. But from a user’s point of view. he or she won’t have to browse through long tables of contents or search for the right topic. The help is essentially just one page, right there (hence, minimal).
3. Give users a quick reference guide.
You can give users a short quick reference guide (under five pages). This gets the user up and running with the system. Quick reference guides reduce the instruction for the system to the core tasks and presents those instructions in an abbreviated, concise way. If the user needs more information, point him or her to a full database or online help file where or she can search for answers.
4. Reuse content topics and paragraphs.
If you can reuse the same material for multiple guides, this reduces the amount of documentation you have to write. Especially if you’re writing a manual for several different versions of a product, or role-based guides for different groups of people, or translating your guide into multiple languages, the more you can reuse paragraphs, chunks, and topics, the less documentation you have to manage.
5. Add to the documentation when users request the information.
Don’t fall prey to the mindset that every scenario, problem, and possible use of the application needs documentation. If you set yourself this task, you may be writing hundreds of topics for what is otherwise a relatively simple application. Instead, decouple the help content from the application so you can update it on the fly. Monitor support logs, analyze metrics, and listen to other user feedback. When users ask questions not included in the help, add that topic to the help. This is a living documentation model. The documentation grows to the size it needs to grow, and no larger.
Conclusion
Minimalism in documentation is a growing trend. Recently Chrysler even abandoned their long manuals in favor of shorter guides and DVDs. What are your strategies for minimizing documentation?
Tags: documenting everything, Favorites, information overload, minimalism
Right now, I’m updating the help of my company’s app and my basic strategies are the ones you mentioned in number 1, 2 and 4 (because we also produce manuals). I think 5 is also very useful.
I liked this post because it’s very realistic (at least for my reality), and it doesn’t look like utopia.
[...] Johnson’s blog, I’d Rather Be Writing, posted Minimizing Documentation not a moment too [...]
Those are great tips! And if you needed to sell the reasoning behind this, just factor in the cost of localization. Every word has a cost, multiplied by the number of languages you have to support.
Great advice!
Is less always more?
No, less is less.
What people mean (I assume) is that less text/features etc will produce more results. This isn’t always the case. Imagine if medical companies did less lab testing? Would you really buy their products? If car companies did less, would you feel safe?
The trend towards shorter docs, imho, is due to several factors: time-poor readers, more churn in the document lifecycle, expense of updating long docs and cut-backs in tech doc depts. If you don’t have the writers, you can’t write the docs…
Looking into my crystal ball, I feel that we’re moving towards ‘real-time’ information, i.e. the end of paper manuals (with the possible exception of sop and field documentation).
Technical writers of the future will coordinate the distribution of material, spending time synching content, aligning it to new releases and less on actual text generation.
From a snow-covered Beijing.
Ivan
Another good post Tom. I feel, sometimes it is the client who decides how much information he wants. If our client is a novice user, little informative documentation won’t be helpful. Again, the TWs’ will be blamed of not providing necessary info along with the product.
good post!
its not a fair comparison but gets the message across.
Unfortunately, for ‘Your Company’s APP’, which appears to be a data entry application (majority of most bread and butter programs like these) – it’s bound to have lots of entry fields and little widgets.
This is one of the best reads I have had in weeks. Thanks.
Thanks Graham. This topic is also apparently a growing trend (see my poll in the right sidebar).
Firstly Tom, how did you obtain that screenshot of my company’s product?
I have just forwarded this topic to the System Designers and my Technical Author colleagues as it beautifully puts across points I have been making for some time.
Thanks for backing me up so succintly.
Our product has context-sensitive help and I am currently single-sourcing using XML base files to output HTML for the help and .pdfs for training manuals.
I am trying to push for more interaction between our Support team and documentation so we can publish topics which specifically meet (and reduce) support calls.
Anyway – thanks for confirming my own direction is not too far from really informed thinkers in this arena!
Keep up the good work sir!
Rob
Rob, thanks for your comment. I think the interaction between Support and Documentation is a key strategy that every doc dept should be pursuing.
Re the screenshot of your company’s product — you made me laugh. Yes, it’s too common of a scenario.
I start out with a one-page guide, and by the time that all the reviewers and approvers get done editing, I have 20 pages! How do I reign in everyone, when their opinions are very strong and they get indignant when you don’t incorporate their edits?
[...] out! And I’ll resist the temptation to sharp stick ESRI on this issue! Tip of the hat to I’d Rather Be Writing. …..every time you add something to an interface, you should take something away. Keeping the [...]