Subscribe Bookmark RSS Feed
arati_mejdal

Staff

Joined:

May 21, 2014

Less is more in documentation

I and several other members of JMP recently attended a Minimalism workshop for writers and editors presented by ComTech Services. The workshop focused on reducing the quantity of written content that may be too large or detailed without affecting the quality.

Minimalism, conceived by John M. Carroll at IBM’s Watson Research Center, focuses on text-based learning that encourages exploration rather than role learning. Minimalist theory proposes to get users going right away, minimize reading and make them fill in the gaps themselves. Therefore, minimalist documentation often contains procedures with little or no introduction and explanation. The idea is to include content that is action-oriented, useful and well-suited to the task. Minimalism brings the most important content to the forefront and minimizes distractions for the user.

The four major principles are:

• Incorporate an Action-Oriented Approach – Learn by Doing

• Focus on Users' Real Goals – Support Real Tasks

• Support Error Recognition and Recovery – Learn from Mistakes

• Support Information Access – Locate Information Quickly

We discussed each principle in class and reviewed a checklist to ensure we were incorporating the principle in the content. We were pleased to discover that we have already applied several aspects of each principle in JMP documentation with the refactoring initiative that started with the Basic Analysis and Graphing guide in version 9.

One area that we need to develop, however, is our audience analysis. In order to incorporate a more user-centered approach, we need to learn more about our customers and perform user and task analyses. We need to define our users, prioritize their needs and decide whom to write for. Without that understanding, minimalism degenerates into just making sentences shorter or eliminating sections in the documentation that no one reads.

Minimalists understand that people do not read anything that does not appear to lead to fulfilling their immediate goals. In fact, the shorter and leaner the text, the more likely it is that people will read it. A minimalist approach leads to savings on time and effort used to produce, manage, edit, update, correct, review, publish and otherwise manage content. This also helps remove possible issues with translation and simplifies the message, resulting in a savings in translation costs.

The minimalist agenda focuses on usefulness and usability. Our goal is to write succinct, action-oriented content that allows users to understand quickly what they need to know and do it successfully. Feel free to provide feedback as we continue to apply a minimalist approach to our content.

Article Tags