技术写作与文档2014docs.writethedocs.org
Write the Docs：面向文档写作者的社区与大会
Write the Docs
导读
这是 Write the Docs 文档写作社区的资源站，主张用"文档即代码"的方式来写技术文档：用纯文本或标记语言写作、纳入版本控制、再转换成多种格式发布。对写作者来说，它把流程、工具、风格指南和社区资源集中在一处，尤其适合需要写产品文档、技术文档或团队协作写作的人。
可以直接用的写作要点
- 01
用纯文本或 Markdown 等标记语言写作，并把文档纳入版本控制，比在 Word 里反复转格式高效得多。
- 02
同一份源文件可以生成网页、PDF、纯文本等多种形态，按读者是开发者还是终端用户分别分发。
- 03
写作时参考成熟的风格指南（如 Mailchimp 的《Voice and Tone》、Xerox 出版标准）来统一语气与体例。
- 04
让开发者和非技术写作者都能低门槛参与，同一套文档内外都能共同维护。
HN 评论精选
用标记语言+版本控制+多格式输出，既降低开发者与非技术写作者的协作门槛，又比 Word 流程高效得多，还能服务不同读者。
这很棒——产品经理和技术文档写作者都应该了解这些。感谢作者和这个会议。用这种方式写文档还有一个好处：它对开发者友好，同时对非开发者写作者也可用——而在某些组织里，让开发者提供文档是很难的。让这两类人之间的协作门槛变低实在很舒服，双方都能为内部和外部文档做贡献。我至今还看到有人用 Word 做这类事，而标记语言加上版本控制和文档转换流程，效率要高很多倍。无论是为文档站点生成静态 HTML、为嵌入式或随产品发布的"面向终端用户"文档生成 PDF，还是给开发者用更技术化的纯文本格式——这套流程能照顾到每一种受众，至少对文字文档是这样。
sixdimensional查看英文原文
This is great - the kind of thing product managers and technical documentation writers should definitely know about. Thanks to the authors for providing it and the conference. Another cool thing about docs written this way is they are very developer friendly but still accessible to non-developer writers - and in some cases/organizations, getting developers to provide documentation can be difficult. Having this be low friction between the two groups (say, non-developers and developers) is really quite nice - both can contribute to internal and external documentation. I still find some folks trying to do this kind of thing in Word, and find the markup, source control with the document conversion workflow to be many many times more efficient. Between generating static html for documentation sites, PDFs for embedded/shippable/more "end user friendly" docs and more technical/plain text formats for developers - this workflow has something for every audience/consumer of documentation - at least for written docs.
建议与本地写作社群和企业的风格指南（Mailchimp 语气指南、Xerox 出版标准）建立联系，作为写作文体参考。
我期待更深入地了解，也有几个问题。你们与相关的社群和专业组织有多少接触——无论就这些内容还是就会议而言？比如在奥斯汀，我们有 Content 聚会，还有 Society for Technical Communication 的分会。你们与企业中负责沟通风格指南的写作部门有多少接触？我想到的是 Mailchimp 的《Voice and Tone》，以及最早的 Xerox Publishing Standards：http://voiceandtone.com 和 http://www.janvwhite.org/xerox-publishing-standards。谢谢！
vitovito查看英文原文
I look forward to digging into this deeper, and have a couple of questions. How much contact with related community and professional organizations have you had, both with regards to this content and also the conference? In Austin, we have a Content meetup, and a chapter of the Society for Technical Communication, for example. How much contact have you had with corporate writing departments working on communication style guides? I'm thinking of Mailchimp's "Voice and Tone", and the original Xerox Publishing Standards: http://voiceandtone.com and http://www.janvwhite.org/xerox-publishing-standards Thanks!
作者欢迎投稿扩充内容，并提供电子书大纲和会议、聚会等资源入口。
嗨——我是作者。我很想按评论里说的去扩充这些内容。有更多问题尽管告诉我；如果大家有想说的内容，也非常欢迎投稿。我有一份内容大纲，打算做成电子书，可以看这里：http://docs.writethedocs.org/book/ ——想找个起点的话可以从这儿开始。另外，如果你对这类事情感兴趣，我们在美国和欧洲每年都有大会，美国很多城市也有本地聚会。更多信息：http://conf.writethedocs.org/
forsaken查看英文原文
Hey -- creator here. I would totally love to expand this content, as mentioned in the comments. Let me know if you have any more questions, and would love contributions if there are things people want to say. I have a basic outline for some content I was thinking about turning into an ebook here: http://docs.writethedocs.org/book/ -- if you want somewhere to start. Also, note that if you're interested in this kind of thing, we have a yearly conference in both the US and EU, and local meetups in many US cities. More info here: http://conf.writethedocs.org/
制定文档策略很艰巨，这个站点抓准痛点并给出了可操作的起步步骤。
我最近花了差不多两周时间为公司制定文档策略，所以对这个话题有很多话想说。这是件让人望而生畏的任务，而这个站点确实抓住了其中一些痛点，也给出了很好的起步步骤。强烈推荐！
tericho查看英文原文
I recently spent a good portion of 2 weeks working on a documentation strategy for my company, so I have a lot to say on this topic. It is a daunting task and this site definitely nails some of the pain points and offers great starting steps. Highly recommend!
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选