Shiwei Shang

Thinking will not overcome fear but action will.

主题式写作-如何写参考话题（reference topic）

如何写参考话题 参考话题的作用 参考话题的主要目的是提供查阅型的信息，也就是那些用户在执行任务时可能会临时查找的内容，比如参数列表、命令语法、字段说明、配置选项等。 它不像任务话题那样教你怎么做，也不像概念话题那样解释原理，而是像“速查表”，让用户快速找到具体信息。 参考话题适合包含哪些内容 参数或字段的名称和说明 命令或语法格式 配置选项及其默认值 键盘快捷键、...

Posted by Shiwei Shang on July 2, 2025

主题式写作-如何写任务话题（task topic）

如何写任务话题 任务话题的定位与作用 任务话题是 DITA 中用于描述操作步骤的主题类型，专为指导用户完成具体任务而设计。它强调清晰、简洁、可执行，是技术文档中最贴近用户实际操作需求的内容单元。 撰写任务话题的核心原则 每个主题只描述一个任务 避免在一个主题中混合多个操作流程（如安装与卸载）。 有助于内容的查找、重用与维护。 任务与概念和参考信息分离 任务主题应聚...

Posted by Shiwei Shang on July 2, 2025

主题式写作-如何写概念话题（concept topic）

如何写概念话题 什么是概念话题？ 概念话题的目标是解释“是什么”，也就是为用户提供背景知识、原理说明或某个术语、功能的定义。它不像任务那样教你怎么做某件事，而是帮助你理解为什么要做这件事，或者这件事背后的逻辑是什么。 举例： 在介绍“如何配置数据库”之前，先用一个 Concept 话题解释“什么是数据库连接池”或“数据库的基本结构”。 概念话题话题适合用来做什么？ 解释产品...

Posted by Shiwei Shang on July 2, 2025

主题式写作-介绍

主题式写作 技术文档写作的一个特点就是主题式写作。这篇博文将介绍什么是主题式写作、它有哪些特点、它和常规写作的区别是什么、主题式写作都包含哪些主题以及为什么技术文档要采用主题式写作。 什么是主题式写作（topic-based writing） 主题式写作指的是将信息拆分为独立且聚焦的小单元，每个主题只讲述一个概念（concept）、任务（task）或参考（reference）内容。例如，一个...

Posted by Shiwei Shang on July 2, 2025

谷歌技术文档写作课程笔记 12 如何写错误提示

如何写错误提示 一个好的错误提示包含三部分信息： 指出错误。首先要告诉用户错误是什么，哪里出现了问题。 说明原因。然后告诉用户为什么出错了，是输入错误还是输入的东西不符合要求，正确的输入的格式是什么。 提供办法。最后告诉用户怎么做，可以提供正确的示例。 错误信息的语言同样要求明确，要做到： 简练。 避免双重否定。 分析受众并提供适合他们的信息。用户是技术人员...

Posted by Shiwei Shang on June 27, 2025

谷歌技术文档写作课程笔记 11 无障碍写作

无障碍写作 按照以下建议，让所有人（包括残障人士）都能更加轻松方便地阅读。 给图片提供替代文本（alt text）。替代文本可以方便盲人和弱势人群知道图片包含哪些信息。替代文本还可以优化搜索结果。 使用足够的对比度。合适的对比度可以让视力有问题的人或者在强光下阅读的人看清文字。 使用包容性词汇。不要使用冒犯的词汇。 使用字体、颜色、标志、图片、方位词等增强视觉效果。这些...

Posted by Shiwei Shang on June 27, 2025

DQTI读书笔记8-撰写易查的文档

撰写易查的文档 想要让文档易查，要做到以下几点： 把信息分成概念（concept）、任务（task）和参考（reference）三类。 这三类信息对应着三种话题（topic），即概念话题（concept topic）、任务话题（task topic）和参考话题（reference topic）。每个话题只介绍一个主题，比如有个“把大象装冰箱“的任务话题，这个话题...

Posted by Shiwei Shang on June 27, 2025

DQTI读书笔记7-撰写易懂的文档

撰写易懂的文档 想要让文档易懂，要做到以下几点： 表达清楚。避免使用： 词组，能用单词尽量用单词，尽量简练 模糊的表达，比如kinds of 加强语气的词，比如significantly 长句 没必要的修饰词 空洞的段落 避免歧义。要做到： 避免用多义词 ...

Posted by Shiwei Shang on June 27, 2025

DQTI读书笔记6-撰写准确的文档

撰写准确的文档 想要让文档准确，要做到以下几点： 先理解你要写的东西，然后再动笔，最后再验证你写的东西。不能不懂装懂，泛泛地写，甚至提供错误信息。 跟上技术的变化。每个版本的产品都会在某些方面升级改造，文档定稿前要仔细检查各种版本、商标、产品名是不是与实际相符合。 保持信息的一致。同一件事，不可以在这里是这么说的，在那里就变成了那么说的。可以通过重用的方式让信息保持一致，或...

Posted by Shiwei Shang on June 27, 2025

DQTI读书笔记5-撰写以任务为导向的文档

撰写以任务为导向的文档 以任务为导向的文档就是教用户怎么做的文档。作者要站在用户的角度理解各项任务。对于复杂的任务，应该把它分成多个子任务，避免让话题太长。 面向目标读者 写文档也要“看人下菜碟”。对管理者，文档可能只写整体的任务即可，对于基层操作员，文档要写得足够详细。 以用户视角呈现信息 需要用户操作的地方要用第二人称和主动语态来写，以此来表明操作的执行者是用户自己。 交代任务的背景...

Posted by Shiwei Shang on June 26, 2025

FEATURED TAGS
谷歌技术文档写作课程 DQTI 主题式写作
ABOUT ME

A technical writer, translator, and teacher.

✉️ shiwei.shang@qq.com