This chapter is from the book
This chapter is from the book
This chapter is from the book
Minimalist Writing
No discussion of topic-based writing would be complete without a few words...very few...about minimalist writing. By following minimalist writing principles, you can create more effective topics. In minimalist writing, you should provide only the information that users need, when they need it, and nothing more.
You can find many excellent books and articles that describe minimalist writing in more detail, but remember these important principles: know your audience, remove nonessential content, and focus on user goals.
Know Your Audience
You must understand your users' level of expertise with the product, service, or technology. Do a task analysis so that you know exactly what information users need to accomplish real goals.
Analyze customer support feedback and conduct usability tests to learn about your users:
- What are users likely to know about your product or technology? For example, if your product describes how to create web pages, do you need to explain the basics of browsers?
- What goals do they want to accomplish?
- Will they understand the terminology used for your product? For example, will most of your users who are experienced with search engines know what you mean by "Boolean operators"?
- How much help will they need to resolve problems with the product? How much troubleshooting information should you provide?
Remove Nonessential Content
As a technical writer, you become an expert in the product, service, or technology that you document. Although you might understand your product well, consider what information is essential for your users. Don't create information that users don't need or care about.
This advice might sound like a no-brainer, but you often read technical information that describes the toolbar icons of a simple software product or a step in a task that says, "Type your name in the name field." If your product requires explanation of the toolbar or how to enter a name in a name field, consider improving the product interface rather than creating topics that will probably never be read.
Focus on User Goals, Not Product Functions
Avoid writing task topics that are solely about how the product works. For example, instead of writing a task topic called "Using the User Profile dialog box," which focuses on how the product works, create a task called "Changing user profiles," which focuses on a real goal.
Even for complex enterprise products, such as database or search engine systems, avoid writing lengthy discussions about how the product works. Your users want only enough information to help them set up and use their systems or products.
For example, instead of writing long chapters about how authentication works, start with tasks that show users how to set up security, and explain the options and the benefits of setting up security for various scenarios as they progress through the tasks. You can provide some concept topics, but provide just enough to get users started. Very few readers will be patient enough to read 25 or 50 pages of conceptual material before they start a task.
For more information about writing consistent, minimalist content, see The IBM Style Guide: Conventions for Writers and Editors by DeRespinis, et al.