技术写作与文档2021news.ycombinator.com编辑精选
如何在中等规模工程团队中编写文档？
Ask HN: How to write documentation for a medium size engineering org?
导读
这篇 Ask HN 讨论的是一个约 250 人的工程组织如何摆脱“知识只靠口口相传”的困境：Confluence wiki 缺乏组织、无人负责，代码库分散且难发现，作者想知道如何启动文档工作。对写作者来说，它提醒我们：文档不是一次性写出来的，而是靠降低门槛、明确归属和持续引用慢慢积累。
可以直接用的写作要点
- 01
先降低写作门槛：鼓励一句话 how-to、ADR 等短文档，先让知识进入公共空间，再考虑结构。
- 02
给文档明确的团队归属和维护责任，否则 wiki 很容易失序、过期、无人更新。
- 03
用低摩擦工具链减少贡献阻力，例如 Markdown、网页编辑器、自动检查和链接校验。
- 04
回答同事问题时尽量把链接指回文档，让“写—用—改”形成循环。
HN 评论精选
文档问题应通过专职技术写作者和对开发者体验的投入来解决，而不是指望忙碌工程师自发产出。
如果有 250 名工程师，就负担得起招聘或外包几位优秀的技术写作者。没有什么巧妙技术或方法论能让几百名已经忙碌、甚至过劳的工程师凭空产出高质量技术文档。可以用“开发者体验”向管理层论证：Martin Fowler 写过开发者体验改进如何提升整个团队效率，Spotify 的 Backstage 也是内部开发者平台的例子。
qbasic_forever查看英文原文
If you have 250 engineers (each with a non-trivial salary and total comp) then you can afford hiring or contracting a few good technical writers. That's the solution--there's no slick technology, no methodology, etc. that will make hundreds of already busy and potentially overworked engineers churn out quality technical documentation. Make a case for the value of technical writers, take it to management, build and lead a team to do it... If you need some ammo, devex ('developer experience') is kind of a hot thing in the agile world right now. Martin Fowler has some good recent writings about how improvements to developer experience (of which technical docs are a huge part) vastly improve the efficiency and output of entire dev teams: https://martinfowler.com/articles/developer-effectiveness.html Spotify apparently has invested a ton of money and resources internally into building a first-class devex platform for their teams: https://backstage.io/ Watch some recent talks about it from Spotify folks for great feedback on how it helped their teams. What they've built is exactly what you describe--self-service, low cognitive overhead to start using and sharing tools across the team.
先建立低门槛的文档文化，容忍粗糙，再逐步整理结构。
我们先在团队内建立文档文化，从架构决策记录（ADR）开始。还识别了人们写文档的障碍：大家觉得写文档很费劲，所以我们明确鼓励低投入的一句话 how-to。先把内容放进 wiki 比一开始就设计好结构更重要，之后可以再整理。另外，回答问题时要把人引向 wiki。
mattchamb查看英文原文
We started by building a culture of documentation within our team. A good place to start is with ADRs (architecture decision records). We also identified barriers for people to write docs on random topics. People thought writing docs would be onerous, so we explicitly encouraged low effort one liner how-tos. Getting stuff into a wiki is more important than architecting it properly. You can reorganize it later. You also need to refer people to the wiki to answer their questions. Not saying we have it sorted, but for our corner of this 400 eng org is making progress on useful docs
低摩擦的 Markdown 写作流程加上自动检查，能持续吸引人们贡献文档。
我加入现部门时情况类似：唯一可信来源是一位架构师维护的 80 页 PDF。我的方案是 GitLab 里的 Markdown 文档，再用 mkdocs 生成漂亮的 HTML 页面。18 个月后已有 3000 多次提交、1000 多个文档合并请求。好处包括：Markdown 比 rst 更容易，非开发人员也能用；GitLab WebIDE 有所见即所得编辑器，四次点击就能从修改走到合并请求，不需要懂 git；纯文本方便迁移；CI 会自动检查语法和坏链，流水线通过才能合并。
docsuser3查看英文原文
I totally feel you. When I joined my current department it was pretty much the same. The engineering team transitioned from Jira to another Jira to a company specific PLM solution, and all formatting of existing docs in the process. When I was on boarding I had to talk to so many people to get a brief understanding on all processes, tools, etl, deployment methods, APIs and so on. I made some notes on my way and felt the need to share them with the others because everyone was struggling with that topic. The only one source of truth was a 80 page pdf file maintained by one architect. The solution I went for was markdown docs in Gitlab plus pretty HTML pages generated by mkdocs. The mkdocs material theme is really nice. This has been so successful that we have over 3000 commits after 18 months and over 1000 merge requests to the docs. The main benefits are: * easy to use, markdown is easier that rst. Especially for non dev people. * wysiwyg editor in the gitlab webide. Most changes are made in gitlab itself. From change to merge request in 4 clicks without the need to understand git. * it is just text. In the beginning many people said that they wont contribute anything because the next tool migration will loose everything. But now the docs are in markdown and easily portable. * gitlab ci automatically lints the changes on every commit so that mkdocs doesn't break because of malformed syntax and broken links. You can only merge to master when the pipeline is green. * possibility to peer review. We have regulatory requirements for 4 eye principle of some parts, with merge requests we can easily approve and discuss merge requests. The biggest problem is in my opinion to get our very non technical management onboard. They basically ignore to comment on merge requests or discuss changes in gitlab because it's a developers tool. Therefore they stick to stupid mailing lists and are left out in the process. But everyone from dev to ops, tst, sec is really happy. It would be nice to have a technical writer maintaining and cleaning up the docs, but there is no budget for that, so it's will probably stay my side job.
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选