https://techwriters.org/zh/TechWriters localized technical-writing feed.https://techwriters.org/zh/articles/accessible-code-examples-and-tables/https://techwriters.org/zh/articles/accessible-code-examples-and-tables/Thu, 13 Aug 2026 00:00:00 GMT文档可访问性并不止于导航和对比度。代码示例、JSON 响应和参考表格也必须在不依赖颜色的情况下保持清晰、可理解、可使用。https://techwriters.org/zh/articles/ai-as-editor-not-oracle/https://techwriters.org/zh/articles/ai-as-editor-not-oracle/Thu, 13 Aug 2026 00:00:00 GMT围绕“把 AI 当编辑，而不是神谕”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“把 AI 当编辑，而不是神谕”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/ai-fact-checking-for-docs/https://techwriters.org/zh/articles/ai-fact-checking-for-docs/Thu, 13 Aug 2026 00:00:00 GMT生成式文本可以看起来非常完整，却悄悄捏造默认值、保证或引用。验证流程应围绕权威来源、可执行示例和明确的不确定性构建。 AI 文档中最危险的错误通常不是语法错误，而是可信但没有依据的陈述：默认 timeout、未记录的参数、兼容性保证，或指向错误内容的 citation。https://techwriters.org/zh/articles/ai-learned-to-write-documentation/https://techwriters.org/zh/articles/ai-learned-to-write-documentation/Thu, 13 Aug 2026 00:00:00 GMT三年间，生成式 AI 把昂贵的初稿变成了廉价操作。现在真正重要的问题不再是模型会不会写，而是谁对事实、结构、审核、更新与质量负责。https://techwriters.org/zh/articles/api-examples-that-teach/https://techwriters.org/zh/articles/api-examples-that-teach/Thu, 13 Aug 2026 00:00:00 GMT技术上有效的 request 不一定是好示例。选择能够解释 API 心智模型、使用真实值，并帮助开发者预测下一步的示例。https://techwriters.org/zh/articles/authentication-docs-that-prevent-support-tickets/https://techwriters.org/zh/articles/authentication-docs-that-prevent-support-tickets/Thu, 13 Aug 2026 00:00:00 GMT围绕“减少支持工单的认证文档”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“减少支持工单的认证文档”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/books-and-guides-for-technical-writers/https://techwriters.org/zh/articles/books-and-guides-for-technical-writers/Thu, 13 Aug 2026 00:00:00 GMT真正有用的阅读清单不再只是经典书目。把 Microsoft、Google、GitHub、IBM 的现行指南放在一起比较，用 Diátaxis 检查内容结构，并把每次阅读变成一次真实的文档练习。https://techwriters.org/zh/articles/choosing-a-docs-generator/https://techwriters.org/zh/articles/choosing-a-docs-generator/Thu, 13 Aug 2026 00:00:00 GMTSphinx、MkDocs、Astro 等工具针对不同内容模型和团队优化。应比较作者流程、扩展能力、本地化和维护成本，而不是只看演示页面和功能清单。https://techwriters.org/zh/articles/choosing-search-for-docs/https://techwriters.org/zh/articles/choosing-search-for-docs/Thu, 13 Aug 2026 00:00:00 GMT围绕“选择文档搜索：从失败查询开始”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“选择文档搜索：从失败查询开始”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/deliberate-practice-for-docs/https://techwriters.org/zh/articles/deliberate-practice-for-docs/Thu, 13 Aug 2026 00:00:00 GMT阅读文档理论有帮助，但能力增长更快的方式，是反复完成小型调研、重构、编辑和验证练习，并获得明确反馈。 “提高技术写作能力”太宽泛。一次只练一个能力：减少歧义、设计 procedure、采访 engineer、编辑 API example、重构导航或建立术语表。https://techwriters.org/zh/articles/diagrams-as-code-in-documentation/https://techwriters.org/zh/articles/diagrams-as-code-in-documentation/Thu, 13 Aug 2026 00:00:00 GMT围绕“图表即代码：什么时候有用，什么时候没有”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“图表即代码：什么时候有用，什么时候没有”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/docs-as-code-without-fanaticism/https://techwriters.org/zh/articles/docs-as-code-without-fanaticism/Thu, 13 Aug 2026 00:00:00 GMTDocs-as-Code 并不意味着把所有技术写作者都塞进 IDE。更合理的做法是把版本化文本、浏览器编辑、预览、有效的自动检查、人工评审和可预测发布组合起来。https://techwriters.org/zh/articles/docs-tools-then-and-now/https://techwriters.org/zh/articles/docs-tools-then-and-now/Thu, 13 Aug 2026 00:00:00 GMT格式和发布流水线变化巨大，但长期问题依旧熟悉：源文件控制、复用、导航、review，以及让已发布信息与产品保持同步。 在“Docs-as-Code”这个名字出现之前，文档团队已经在处理多个源文件、共享片段、版本手册，以及“哪一份才是最新”的问题。https://techwriters.org/zh/articles/documentation-debt-triage/https://techwriters.org/zh/articles/documentation-debt-triage/Thu, 13 Aug 2026 00:00:00 GMT围绕“文档债务：如何找到真正伤害用户的问题”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“文档债务：如何找到真正伤害用户的问题”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/documentation-in-ci-cd/https://techwriters.org/zh/articles/documentation-in-ci-cd/Thu, 13 Aug 2026 00:00:00 GMT把文档当作构建产物：在读者看到改动之前验证结构、链接、示例和发布规则。 CI 不能判断解释是否真正有用，但可以在人工投入之前拦截大量可预测问题。https://techwriters.org/zh/articles/documentation-lead-without-bureaucracy/https://techwriters.org/zh/articles/documentation-lead-without-bureaucracy/Thu, 13 Aug 2026 00:00:00 GMT文档负责人应该减少不确定性，而不是成为额外审批层。明确所有权、标准和升级路径，同时让常规发布保持快速，并尽量靠近真正了解产品的人。https://techwriters.org/zh/articles/documentation-metrics-that-matter/https://techwriters.org/zh/articles/documentation-metrics-that-matter/Thu, 13 Aug 2026 00:00:00 GMT围绕“比页面浏览量更重要的文档指标”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“比页面浏览量更重要的文档指标”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/documentation-ownership-map/https://techwriters.org/zh/articles/documentation-ownership-map/Thu, 13 Aug 2026 00:00:00 GMT围绕“不官僚化的文档责任地图”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“不官僚化的文档责任地图”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/documentation-review-workflow/https://techwriters.org/zh/articles/documentation-review-workflow/Thu, 13 Aug 2026 00:00:00 GMT好的评审流程应明确责任、减少等待，并区分事实、编辑与产品审批。https://techwriters.org/zh/articles/documenting-api-errors/https://techwriters.org/zh/articles/documenting-api-errors/Thu, 13 Aug 2026 00:00:00 GMT围绕“如何记录 API 错误，让开发者能够恢复”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“如何记录 API 错误，让开发者能够恢复”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/documenting-rest-api/https://techwriters.org/zh/articles/documenting-rest-api/Thu, 13 Aug 2026 00:00:00 GMT好的 API 文档需要把机器可读契约、人类解释、可运行示例和明确的错误行为结合起来。 REST API 文档同时面向机器和人。机器可读契约描述 path、method、parameter、schema 与 response；人类文档解释意图、约束、工作流和开发者要做的选择。https://techwriters.org/zh/articles/editing-drills-for-technical-writers/https://techwriters.org/zh/articles/editing-drills-for-technical-writers/Thu, 13 Aug 2026 00:00:00 GMT围绕“提升技术写作的编辑练习”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“提升技术写作的编辑练习”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/entering-technical-writing/https://techwriters.org/zh/articles/entering-technical-writing/Thu, 13 Aug 2026 00:00:00 GMT三年前，新人只要写作清楚、掌握几种工具并准备作品集，就有机会进入技术写作。到 2026 年，入口明显变难：AI 能快速生成初稿，团队更精简，technical writer 还必须会验证事实、理解 API、使用 Git，并对文档系统负责。https://techwriters.org/zh/articles/first-90-days-in-documentation-team/https://techwriters.org/zh/articles/first-90-days-in-documentation-team/Thu, 13 Aug 2026 00:00:00 GMT围绕“加入文档团队的前 90 天”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“加入文档团队的前 90 天”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/forum-questions-that-aged-well/https://techwriters.org/zh/articles/forum-questions-that-aged-well/Thu, 13 Aug 2026 00:00:00 GMT工具名称变化很快，但术语、所有权、截图、复用和审核的问题一直回来，因为它们反映的是更深层的系统设计选择。 技术答案从共享目录变成 repository 和 ownership rule，但组织问题没有改变。https://techwriters.org/zh/articles/glossaries-and-terminology/https://techwriters.org/zh/articles/glossaries-and-terminology/Thu, 13 Aug 2026 00:00:00 GMT术语表真正有价值，是因为它能约束产品、界面和文档中的选择，而不仅是收集词语。 有用的术语记录不仅解释词义，还应包含首选词、禁用或废弃变体、上下文、语法说明和 owner。https://techwriters.org/zh/articles/hiring-technical-writers-without-trick-tests/https://techwriters.org/zh/articles/hiring-technical-writers-without-trick-tests/Thu, 13 Aug 2026 00:00:00 GMT围绕“不靠陷阱测试招聘技术写作者”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“不靠陷阱测试招聘技术写作者”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/hypertext-before-modern-docs-portals/https://techwriters.org/zh/articles/hypertext-before-modern-docs-portals/Thu, 13 Aug 2026 00:00:00 GMT围绕“现代文档门户之前的超文本”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“现代文档门户之前的超文本”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/information-architecture-for-growing-docs/https://techwriters.org/zh/articles/information-architecture-for-growing-docs/Thu, 13 Aug 2026 00:00:00 GMT五十页时好用的结构，到了五百页可能彻底失效。应围绕用户任务、内容类型和长期稳定的概念设计导航，而不是照搬组织架构。 小型文档集几乎可以容忍任何导航方式。只有二十页时，读者能快速扫完菜单，作者也记得内容放在哪里，重复内容仍然容易发现。https://techwriters.org/zh/articles/learn-api-docs-by-building-a-small-api/https://techwriters.org/zh/articles/learn-api-docs-by-building-a-small-api/Thu, 13 Aug 2026 00:00:00 GMT围绕“通过构建一个小 API 学习 API 文档”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“通过构建一个小 API 学习 API 文档”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/llm-content-pipeline-guardrails/https://techwriters.org/zh/articles/llm-content-pipeline-guardrails/Thu, 13 Aug 2026 00:00:00 GMT当模型能够大规模创建和更新文档时，验证也必须同比扩展。限制输入、保留来源、验证结构，并把“生成”与有权限的“发布”分开。 好的架构预设模型有时会错。可以让模型提出文件、元数据和修改，但不要让同一步骤静默发布。https://techwriters.org/zh/articles/markdown-at-scale/https://techwriters.org/zh/articles/markdown-at-scale/Thu, 13 Aug 2026 00:00:00 GMT围绕“大规模 Markdown：避免仓库失控的约定”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“大规模 Markdown：避免仓库失控的约定”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/openapi-as-source-not-documentation/https://techwriters.org/zh/articles/openapi-as-source-not-documentation/Thu, 13 Aug 2026 00:00:00 GMTOpenAPI 描述可以生成准确的 reference 结构，但开发者仍需要概念、任务流程、身份认证、示例和错误恢复，这些不是一个 schema 能单独解释的。 OpenAPI 非常擅长描述 operation、parameter、request/response 结构、status code 和可复用 schema。https://techwriters.org/zh/articles/portfolio-for-technical-writer/https://techwriters.org/zh/articles/portfolio-for-technical-writer/Thu, 13 Aug 2026 00:00:00 GMT招聘团队需要看到你如何调研、组织和验证文档。强有力的作品集应说明问题、约束、过程和结果，而不是只展示漂亮截图。 一篇漂亮文章只能证明你能写出漂亮文字，却无法说明你如何发现缺失信息、选择受众、处理冲突要求或验证最终步骤。https://techwriters.org/zh/articles/release-notes-users-can-act-on/https://techwriters.org/zh/articles/release-notes-users-can-act-on/Thu, 13 Aug 2026 00:00:00 GMT围绕“让用户知道该做什么的发布说明”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“让用户知道该做什么的发布说明”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/structured-writing-rules-that-scale/https://techwriters.org/zh/articles/structured-writing-rules-that-scale/Thu, 13 Aug 2026 00:00:00 GMT规模化一致性来自内容模型、术语和可复用模式，而不是要求所有人背下巨大 style guide。重要规则应写进 schema 和组件。 小团队可以依靠共同习惯和直接编辑。贡献者达到几十或几百人后，记忆就不再是控制系统。https://techwriters.org/zh/articles/style-guide-people-use/https://techwriters.org/zh/articles/style-guide-people-use/Thu, 13 Aug 2026 00:00:00 GMT围绕“真正有人使用的写作规范”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“真正有人使用的写作规范”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/synthetic-examples-and-hallucinations/https://techwriters.org/zh/articles/synthetic-examples-and-hallucinations/Thu, 13 Aug 2026 00:00:00 GMT围绕“合成示例：有用的草稿，危险的证据”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“合成示例：有用的草稿，危险的证据”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/technical-writer-2006/https://techwriters.org/zh/articles/technical-writer-2006/Thu, 13 Aug 2026 00:00:00 GMT工具已经彻底变化，但职业核心仍然熟悉：受众、证据、结构、术语和责任。 2006 年的技术写作者更常使用桌面出版、办公格式和手工维护的帮助系统。https://techwriters.org/zh/articles/technical-writer-skills-matrix/https://techwriters.org/zh/articles/technical-writer-skills-matrix/Thu, 13 Aug 2026 00:00:00 GMT好的技能矩阵用于成长和招聘；坏的矩阵只是把模糊性格特征包装成精确数字。应衡量可观察的文档能力，以及一个人能够独立承担的问题复杂度。https://techwriters.org/zh/articles/vale-style-linting/https://techwriters.org/zh/articles/vale-style-linting/Thu, 13 Aug 2026 00:00:00 GMT样式 linting 最有价值的地方，是发现术语漂移、风险措辞和可重复的编辑缺陷。规则应少而明确，并保持足够安静，让一次失败真正值得作者注意。 样式 linter 可以在几秒内检查成千上万句子，因此很容易产生“把所有偏好都编码进去”的冲动。https://techwriters.org/zh/articles/wcag-22-for-documentation/https://techwriters.org/zh/articles/wcag-22-for-documentation/Thu, 13 Aug 2026 00:00:00 GMT无障碍不只是前端任务。文档作者直接控制标题、链接目的、替代文本、表格、操作说明，以及辅助技术依赖的内容结构。https://techwriters.org/zh/articles/when-manuals-shipped-on-cd/https://techwriters.org/zh/articles/when-manuals-shipped-on-cd/Thu, 13 Aug 2026 00:00:00 GMT围绕“当用户手册随 CD 一起交付”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“当用户手册随 CD 一起交付”，重点是可执行、可验证和可维护的做法。https://techwriters.org/zh/articles/working-with-subject-matter-experts/https://techwriters.org/zh/articles/working-with-subject-matter-experts/Thu, 13 Aug 2026 00:00:00 GMT围绕“如何与领域专家高效评审而不是不停开会”给出可执行、可验证并且便于长期维护的技术写作方法。 从技术写作角度解释“如何与领域专家高效评审而不是不停开会”，重点是可执行、可验证和可维护的做法。