【Topic-Based Writing 】美国老编谈心得

Topic-based Writing说来接触它有十来年了：

• 在UT工作时，2006年开始，Techincal Writer们就开始研究类似的写法。当时，大家还不知道这个术语，也是想提高文档的可读性与易用性。最后想到的解决方法是：以读者日常使用的任务为索引组织文档，每个任务都强制加上【任务描述】、【操作入口】、【操作步骤】等tag。
• 入职MA后，在2012~13年开始，北美team组织安排线上Seminar，请了加拿大的SmartPublisher公司，给全球三个文档组开了线上Webex培训。分两个session系统地讲述了Topic-based wrting。但由于当前还未在组内推行DITA，所以文档写作上，也没有硬性的format(tag)来规范或是强制TW的写作风格。自从2016年下半年，组内全面推行Oxygen DITA Style后，DITA采用严格的样式规范，保证了大家在写作时，有意识地区别Concept、Task, Reference三类主题，并保证各主题的元素不缺失。

有了上述做保障，topic-based writing难点就突显在如何将内容任务化、粒度、深度。 即便是同一类读者，也可以分Novice, intermedia, advanced几等。Writer在学习到TBW理论知识后，还需要平时多去研究大公司经典文档的写作方法。我个人很欣赏Adobe DreamWaver的Getting Started Guide。把这份大文档保存在电脑上，不时拿出来学习、效仿、揣摩。

当时组里刚招到一个资深编辑Utpala Unand。Utpala是一个有着20多年技术写作的Writer，近几年转而做Tech Editor。当初我也参与她的面试，与她电话1小时，相谈甚欢，很多问题上有着共鸣。为此，我让她帮列出了美国可供学习的TBW手册，以及她对TBW的经验与实际操作方法。（有兴趣的同学，可上LinkedIn搜索并加她关注）

For a pure topic-based-authoring ( TBA) approach, look at the following:

• ** DITA Style Guide** (it is very topic-based; only one idea at a time.).

Microsoft IIS 6.0 Documentation

• Under the ** Microsoft Server Administration Guide (IIS 6.0) **, look at these examples—
  **Web Site Administration section for Concept-type information. Another example - from the TOC, go to Getting Started with IIS 6.0 (3rd
  listing from top) > IIS 6.0 Features > Security Features (IIS 6.0)
  **Configuring Applications in IIS 6.0 ** > Enabling ASP Debugging (IIS 6.0) to see Procedures-type information.

• IIS 6.0 Reference section (2nd
  last listing in TOC) and any sub-topic under it or Troubleshooting in IIS 6.0 > HTTP Status Codes in IIS 6.0 for Reference-type information. Notice how all of the Reference information is pulled into one section.

• Configuration Guide for SAS 9.4 Foundation for Microsoft Windows for x64. Notice how task-based this guide is. There is no use of x-references in procedures and all required x-reference is provided in the ‘concept’ part of the explanations, leaving procedures uncluttered.

• Configuration Guide for SAS 9.4 Foundation for UNIX. See Chapter 1 for example of how the audience and related information are identified. (The section titled ‘Understanding this Book’ is not necessary or good practice, so ignore this). J Chapter 3 is more about concepts and overviews and is pulled out separately. It includes a lot of reference information. Also see chapters 10 and 11.

Note: TBA examples are only for you to understand how documentation is being very specific to each topic/task and to see examples of how to weave concept, task and reference together.

系列文章

• Topic-Based Writing：美国老编谈心得-续
• Topic-Based Writing: 安装手册实例剖析
• Topic-based writing: 安装手册经典作品点评
• Topic-Based Writing: Planning Your Topics
  .