How to Apply Topic-Based Writing

In the first session, I talked about my practices on topic-based writing (http://www.jianshu.com/p/6dd1eac4ff38). In this session, I will talk about new findings I spotted online, which inspired me and call up my resonation.

I didn't get any chance to discuss my concern with our editor in SF (Utpala). On a very casual occasion, I came across http://idratherbewriting.com/, a website running by a very experienced and diligent Tech Writer. He also runs a series of PodCast by himself and sometimes with guest speakers. I resonates with him on many of his ideas.

One of his July posts (http://idratherbewriting.com/2017/07/23/pain-of-ignorance-versus-pain-of-learning/ ) talks about topic-based writing. I write down below thought-provoking points which I have resonation with:

He threw out the question after finding that users read documentation only when the pain of ignorance overweigh the pain of learning, so how can TWs design docs to accommodate a mindset of impatient frustration? Undoubtedly, this answer is Topic-Based Writing.

Very soon, the writer turned to my concern--topic-based writing vs linearity by raising a fact--**"That’s why it’s hard to take a user from a true start to finish, because the number of permutations and end goals usually vary. You can rarely walk a user from the absolute start to the absolute end to help them achieve their goal. Their path is too specific, and you’d have to write a dozen different similar but slightly variant paths for every business scenario and user. As a result, the topic-based documentation requires the user to find, order, and assemble the sections he or she needs. The portrayal of the easy 1-2-3 steps to achieve the task (thanks Marketing!) was an illusion. Reality is multi-sectioned, multi-branched, and multi-pathed. It doesn’t have a clear order between sections or flow of branches or paths."

The conclusion of this episode contains:

• Most users turn to tech docs only when the pain of ignorance exceeds the pain of learning.
• At the moment users get frustrated enough to submit to learning documentation, they’re in a state least likely to get any learning done.
• Most users “read to do.” Task-based documentation is the best approach to suit impatient doers who want to do a task.
• Linear tasks are an illusion, since reality is more multi-pathed, branching, and messy.
• Beginning-to-end workflows are too personal and unique to document for everyone. As a result, tasks are chunked into small sections that users have to find, order, and assemble for their needs.
• How tech docs are evaluated depends on the state of mind of the user. The same tech docs can either suck or rock depending on the user’s mental state.

有些人可能会说作者是在推卸负责，尤其是看到“How tech docs are evaluated depends on the state of mind of the user. The same tech docs can either suck or rock depending on the user’s mental state.” 但我与他点确有共鸣：现实是多样的，充满各种分支，混乱复杂。Topic-based writing也只能列出用户可能用到任务，但用户如何找到有用的操作任务信息，如何排序组合这些任务完成自己的工作，还是需要用户根据实际情况自行灵活处理。当然TW必须始终以简轻用户学习痛苦，吸引用户去阅读文档为已任。就象作者写的:
Pretty much every technique in tech comm is an effort to reduce the pain of learning doc:

• simple sentences
• short paragraphs
• subheadings
• consistent terminology
• glossaries
• screenshots and illustrations
• workflow maps
• troubleshooting sections
• context-sensitive help
• search and facets
• document metadata
• emotional language

回到《安装手册》的写作上--我觉得本人基于事例的写法，不仅体现了我与作者观点的认同、并且是一个对“读者阅读文档”现实情况的应用与拓展。为了写清一个复杂问题，示例永远是一个好的演示教导读者的方法。此外，给出操作前提（准备事项）也是限制与明确写作场景的一个必要手段。