技术写作导论#

写作#

写作是伴随我们一生的基本技能。从小学语文课本中的简单造句、看图写话，到初高中阶段的记叙文、议论文、说明文，我们不断学习如何组织语言、表达观点和传递信息。这些基础训练帮助我们掌握了如何清晰、有效地表达思想。

体裁#

写作的形式丰富多样，常见的体裁包括：

记叙文：强调时间顺序，注重情节的生动性，旨在讲述故事、表达情感。
议论文：注重逻辑推理，通过论点、论据和论证，阐明观点，力求说服读者。
说明文：以客观事实为主，清晰解释事物的特征、用途或原理。
散文：表达作者的个人感受和体验，语言优美，富有韵味和感染力。
传记/自传：以人物生平或个人经历为叙述对象，旨在还原事迹与心路历程。

学科或者行业#

随着社会的发展，伴随着不同的学科或者行业，出现了更多细分的写作类型，例如：

技术写作：为工程师和终端用户提供准确、结构化的操作指南、API 文档和故障排查，帮助快速上手与排障。
实用写作：涵盖商务公文、报告、申请书等，重在信息的实用性和明确性。
创意写作：包括小说、诗歌、剧本创作，强调创新性和想象力。
科学写作：通常用于学术论文、研究报告，要求严谨、客观和系统。
医学写作：遵循循证医学和法规要求，撰写临床研究报告、病例报告及患者教育材料，将专业知识转化为可理解信息。
商务写作：通过商业计划书、市场分析与销售提案等文档，用专业措辞和逻辑结构促进决策和合作。

写作目的#

亚里士多德（Aristotle）在《修辞学》中提出的三大修辞分支——议政（面向未来的劝说）、司法（回顾过去的审判与辩护）和颂扬（聚焦当下的赞美或谴责）——奠定了“说服”写作的基础；詹姆斯·L·金尼维（James L. Kinneavy）1971 年在《A Theory of Discourse》中又将写作分为表情（表达作者自我与情感）、指称（客观陈述世界信息）、劝服（影响读者态度或行为）与文学（追求文本审美），强调在“作者–文本–读者”的三角中选择焦点；罗曼·雅各布森（Roman Jakobson）1960 年提出的语言六功能——指称、情感、呼语、寒暄、元语言和诗性——进一步细化了每段文字在传递信息、表达态度、促动行动、维系交流、讨论语言和追求形式美上的主次功能；而韩礼德（M.A.K. Halliday）的系统功能语言学则从概念（表意）、人际（互动）和篇章（组织）三大元功能视角，揭示了写作既要反映世界、建立作者–读者关系，又要确保文本连贯。实践中可先借金尼维定位“主要投射”（自我、世界或读者），再参考亚里士多德制定说服策略，用雅各布森检查是否需增添呼语或寒暄细节，最后以韩礼德审视概念与篇章结构及人际语气，确保文本既精准、连贯，又具感染力与可操作性。

简单来说通常有如下写作目的：

功能	主要侧重	典型示例
叙述	讲故事、呈现时间线	小说、游记、案例故事
描写	营造感官或情感氛围	风景散文、人物速写
说明	客观解释概念/过程	科普文章、技术手册、百科条目
论证	提出观点并给出证据	学术论文、社论、政策简报
劝说 / 促动	影响态度或行动	市场文案、公益倡议、募捐信
娱乐 / 审美	激发情感、审美体验	诗歌、戏剧、幽默专栏

技术写作#

技术写作（Technical Writing）是一种以清晰、准确、简洁为核心目标的专业写作形式，旨在将复杂的技术信息转换为目标读者易于理解、使用和操作的文档。它广泛应用于软件手册、产品说明书、操作指南、API 文档、白皮书、技术报告等，用以支持产品开发、用户培训和知识共享。

技术写作的主要目的#

解释概念：通过明确简洁的语言阐释复杂的技术概念，帮助用户快速掌握关键知识。
描述步骤：提供清晰、准确的操作说明和步骤，让用户能够独立、高效地完成任务。
劝说用户：通过展示产品优势、提供使用场景或用户反馈，促使用户理解并信任产品，从而推动其采取行动。

除了上方主要的目的外，结合具体的场景，通常还有“参考索引”，“故障排除”等更为细分的目的。综上所述，技术写作不仅仅是信息的简单传递，更是一种通过精准表达提升用户体验的专业技能。

常见技术文档类型#

用户手册。面向终端用户，涵盖产品安装、基本操作、功能介绍与常见场景示例。
快速入门。帮助新用户在最短时间内上手。
安装指南。详细说明环境依赖、安装步骤、配置参数及常见安装问题解决办法。
API 文档。精确列出接口（函数、类、HTTP 接口等）的签名、参数、返回值、错误码及示例。
开发者指南。针对二次开发或二次集成的工程师，提供项目架构概览、代码组织、最佳实践和扩展示例。
维护手册。针对长期运行的产品或系统，提供定期检查、备件更换、版本升级及报废处理流程。

技术写作的专业性#

因为我们都会写作，是否工程师直接创作对应文档即可，为什么需要学习技术写作，或者由专业的文档工程来创作对应文档呢？

我们可以来尝试一些挑战：

挑战1：解释墨卡托投影

你可以尝试一下百度或者Google进行搜索，看是否有人可以将你说明白这个概念。

挑战2：2秒钟学会叠T恤

可以拿一件T恤看是否学会，是不是眼睛会了，但是手还不会？

挑战3：劝用户将API从V1升级到V2

仅仅告知“API v1 将于年底停止支持，请使用 API v2，几乎注定失败。

从这些挑战来看，完成技术写作的沟通目的并非易事。

工程师写技术文档面临的挑战#

知识诅咒#

当我们越懂一件事情的时候，越难跟别人解释，这是一个典型的认知偏差，也称为“知识的诅咒”（The Curse of Knowledge）。工程师在开发过程中，已经内化了大量的背景信息、架构决策和专业术语。他们在写文档时，会无意识地假设读者也具备这些知识，从而导致内容的跳跃和缺失。工程师倾向于描述一个系统“是什么”（What it is），它的构成、它的API列表、它的技术实现。他们习惯于使用精准但晦涩的内部术语，因为这是他们团队内部最高效的沟通方式。

用户视角#

用户通常不关心具体技术，只想解决自己的问题。用户通常带着一个具体的目标而来，他们更关心“如何用它来完成某个任务”（How to do it），例如如何启用Word的可读性指数的检查；以及“我为什么要这样用它”（Why should I do it this way），例如可读性指数可以让我们快速知道文本的阅读难易程度。

从这个角度来看，工程师并不适合撰写技术文档，因为难易共情非同类工程师用户，除非文档工程师接受相应的写作训练，从而能有读者意识。

术业专攻#

以程序员为例，工程师更善于编写各类代码，而非花大量时间去做自己非专业的事情，因为理解用户，为特定用户设计合适的写作策略，验证文档的正确性等等都需要专业技能，而这些并非开发工程师擅长的，专业化的社会是让每个人做自己最擅长的，然后分工协作达到系统最优。

专业技术文档工程师#

既然是专业的事情，那就需要交给专业的人，在技术写作这个行业，则是由技术文档工程师担当各类文档创作的任务，他们通常会具备：

技术理解。懂所撰写的技术，一般能阅读源码、API 及架构图，准确抓住关键工作原理与边界条件。
写作表达。能用简洁、一致、受众友好的语言阐释复杂技术；熟悉中/英文技术写作规范。熟悉通用写作风格指南，并能按照特定风格写作。
排版学知识。字体，版面，版心等桌面出版和信息出版的知识。
用户为中心的设计。能以用户目标为中心规划导航、索引、示例和步骤，降低认知负荷。
信息采集与需求澄清。通过 SME 访谈、日志分析、问卷调查等手段获得可靠素材并验证文档需求。
评估与测试。设计任务驱动测试、眼动/点击路径分析，基于认知负荷和任务完成率迭代内容。
工具栈。Markdown / XML-DITA、Git、静态站点生成器、图形截取与流程图工具、CI/CD。
GenAI 与自动化应用。利用 LLMs 进行草稿生成、样例代码插桩、文档质量检查，持续提升效率与质量。

技术写作导论

目录