技术写作与文档2013news.ycombinator.com
Ask HN：关于太空行走程序写作的建议？
Ask HN: Suggestions for spacewalk procedure writing?
导读
这是 NASA 工程师在 Hacker News 上求助：如何编写航天员出舱（EVA）这类多角色、多线程并行的操作流程文档。目前他们用 Word 的大表格按列排各角色步骤，排版耗时巨大，还想要版本对比、多人分工编辑。写作者可以从中看到「结构化写作 + 版本控制 + 模块化拆分」的思路，对写任何多线并行的说明文、流程文都有启发。
可以直接用的写作要点
- 01
多线并行的内容不要写成连续段落，用分栏表格或时间线布局，让「谁在第几步做什么」一眼可见，先后顺序用垂直位置表达。
- 02
把长文档拆成可独立编辑的子模块（子流程引用子流程），像代码一样分文件维护，多人协作时冲突最少、复用最方便。
- 03
用纯文本格式＋版本控制（git 等）管理修订历史，逐行 diff 比 Word 的修订痕迹更精确，也更容易回滚和合并。
- 04
排版工具只负责呈现，不会帮你检查逻辑顺序是否合理；流程的正确性需要单独校验，别把格式正确当成内容正确。
HN 评论精选
多角色并行的流程本质是排程问题，可借用项目管理／甘特图工具而非文字处理器。
按你描述的需求——EV1、EV2、舱内机械臂操作员和地面任务控制中心并行作业，有时相互独立、有时紧密耦合——这其实更像一个项目管理问题。与其用 Word，不如用 Excel 做甘特图，或者用建筑、工程、油气等行业常用的 Asta Power Project 这类工具，它支持拖拽排程、实时查看多个并行项目、优化资源并生成报表。
itsprofitbaron查看英文原文
Reading your requirements specifically in relation to the procedures using “2 astronauts working outside the space station (called EV1 and EV2), plus a robotics operator inside, and other actions taken by mission control on the ground. All of this is happening in parallel. Sometimes EV1 may be working on a task where all the steps can be done independent of what EV2 is doing, while other times their steps are heavily intertwined. The same goes for robotic and mission control steps” it seems like you need a project management tool. Whilst you’re currently using Microsoft Word for this, it would actually be much easier to do this using Excel (and create a Gantt Chart) OR you could use something like Asta Power Project[1] which is used in the Construction Industry as well as with Technology Organisations, Engineering, Manufacturing, Oil & Gas and Financial Services etc which rely on projects running in parallel. The reason I recommended the Asta Power Project tool is because you can: - Create accurate schedules easily using a drag/drop feature - Have complete visibility over multiple projects in real-time - Optimise your project resources - Access powerful reporting tools - ETC I've actually used the Asta Power Project Software myself; it's pretty powerful and feature rich. [1] http://www.astadev.com/products/asta-powerproject/
用文本定义任务＋版本控制＋自动生成报告，可同时满足并行、分工、diff 和资源分配需求。
TaskJuggler 是免费开源工具，从文本文件读取任务定义，自动排程并生成甘特图等自定义报告，还允许把任务定义拆到多个文件。配合 git 之类的版本控制，你就能：用文本定义多资源并行的流程、生成流程说明报告、对整个修订历史做 diff（文本 diff 是最成熟的对比合并工具）、让多人像做软件开发一样协作。它的资源不一定是人，可以指代工具设备，或许能满足你追踪器材位置的需求。缺点是它面向以周／年为单位的长期项目，时间粒度可能不够细。
weinzierl查看英文原文
TaskJuggler[1] is a free and open source software that can read task definitions from text files, schedule them and generate freely definable custom reports (including Gantt Charts). TaskJuggler allows you to partition the task definitions into several files. Together with a version control system (like git) this will allow you to: - define procedures with multiple resources working on tasks in parallel in a text file - generate a report describing the procedure - diff the entire revision history (text diff has the most advanced diff and merge tools) - allow multiple editors ... a lot like in software development For your bonus requirement: In TaskJuggler you can assign resources to tasks, and resources don't need to be people. I don't know if this solves the problem of which tool is where, but TaskJuggler is very flexible. One thing that could turn out to be a problem is that TaskJuggler is meant for longer running projects (weeks to years). Maybe time resolution is not enough for your purpose. [1] http://www.taskjuggler.org/ [2] http://en.wikipedia.org/wiki/TaskJuggler
LaTeX＋git 能实现模块化协作和版本历史，但只解决排版，不校验流程逻辑。
我们用 LaTeX 加代码仓库。LaTeX 可以把文档拆成许多小文件供不同人编辑，还能用 \include 只编译其中一部分成 PDF。好的仓库（git 跨平台可用）能自动合并，只要不同时改同一处就没问题。输出 PDF 可以做得和原来的 Word 文档一样，图表自动处理，修订历史由仓库负责。缺点是它像写 HTML，有人不喜欢这种写法；而且它只是排版方案，不会自动做时序检查（比如验证顺序是否正确、有没有重叠），但总体比 Word 强。（说真的，航天机构为什么都离不开 Word？ESA/DLR 给我们的 LaTeX 模板就是从 Word 转换来的，满是错字还编译不了。）
kaybe查看英文原文
We're using LaTex with a repository. Latex allows to split the document into many small files that can easily be worked on by different people. You can even split them further, and also compile just parts into pdf documents (\include to the rescue!). A good repository (git works well multiplatform) can merge (automerge is very good) so it's not a problem if people work on the same file at the same time, as long as it's not exactly in the same place. There are pretty pdf output files (which can be made to look like the normal word documents if it is needed). Graphs and Figures are handled automatically. Sometimes they don't do what one wants, but there is very extensive documentation out there. The repository also takes care of the revision history. Problems that I could see is that it's similar to writing html. Some people don't like this and might not want to use it. It's just a typesetting solution and will not do automatic time management (like checking that all is in the right order, or see what overlaps), but it is more powerful than Word. (Seriously though, what is it with space agencies and Word? ESA/DLR sent us a mangled uncompilable latex template full of typos which said it came from "word-to-latex".)
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选