核心技能与工具

技术写作不是「文笔好」就够，需要 信息架构、版本协作、轻量自动化 三件套。BI 分析师用 SQL 取数；技术写作者用 Markdown + Git 管文档生命周期。

学习目标

• 掌握 Markdown 文档结构与常见扩展语法
• 理解 Git 在文档 Review 与版本追溯中的作用
• 建立编辑工具与 AI 辅助写作的边界意识

核心概念

Markdown 写作基线

元素	用途
# 标题层级	可扫描的信息结构
代码块 + 语言标签	语法高亮与复制友好
表格	参数、对比、兼容性
链接与锚点	跨页导航、Deep Link

限制：复杂排版、交互组件需 CMS 或静态站点生成器。文档源文件优先 Markdown，发布层再渲染。

Git 文档工作流

main — 已发布文档
feature/docs-quickstart — 单篇或单模块改动
PR Review — 工程校验步骤、产品校验措辞
tag / release — 与产品版本对齐

与代码同仓（docs-as-code）的好处：示例可测、变更有 blame、Release Notes 可关联 commit。

编辑与生成工具

• IDE / VS Code：多文件、预览、Lint
• ** Vale / alex**：风格与 inclusive language 检查
• AI 辅助：起草段落、改语气；事实、步骤、版本号必须人工核验

必备软技能

好奇心 — 愿意读源码与跑命令
结构化 — 先大纲后正文
同理心 — 站在首次使用者视角
耐心 — 反复试步骤直到零歧义

练习

• 用 Markdown 写一段含标题、表格、代码块的 20 行示例
• 在 Git 分支上改一篇文档，模拟 PR 描述（改了什么、如何验证）
• 列出 3 条「AI 可帮 / 不可帮」的技术写作任务

小结

Markdown 写结构，Git 管版本，工具提效但不替代事实校验。 下一课区分 How-to、Troubleshooting 等内容类型。