技术写作与文档2015maryrosecook.com
用六百字讲清 Git
Git in six hundred words
导读
这篇帖子是Mary Rose Cook的《Git in six hundred words》，用极简篇幅介绍Git。评论指出这种简单介绍掩盖了实际使用中的复杂性和困惑，并推荐用寓言故事（The Git Parable）来解释，同时引发关于用户是否需要理解工具内部实现的讨论。对写作者的启发是：解释复杂概念时，如何平衡简洁与完整、用故事降低门槛、考虑读者背景。
可以直接用的写作要点
- 01
用极简篇幅解释复杂概念时，要意识到可能掩盖实际使用中的陷阱，写作时需权衡简洁与完整。
- 02
用寓言或故事（如“The Git Parable”）来解释抽象技术概念，能降低理解门槛，让读者通过情节记忆。
- 03
写作技术教程时，要明确读者是否需要了解内部实现，避免强制要求读者学习底层细节。
- 04
配合视觉指南或具体示例（如Atlassian的教程）可以帮助读者在基本情境中定位问题，写作时可考虑多模态辅助。
HN 评论精选
简单介绍掩盖了实际使用中的复杂性。
你提交代码到公共仓库。维护者责怪你用了合并而不是快进。你决定从公共仓库引入更多代码。这里有一篇6000字的文章解释rebase是什么意思。你想查看旧版本代码。突然你处于‘detached HEAD’状态。剧终。我热爱Git，但这样简单的介绍隐藏了所有令人困惑的复杂性和尴尬的UI，这些在日常使用中很快会浮现。
NelsonMinar查看英文原文
"You go to commit some code to a public repo. The maintainer scolds you for using merges instead of fast forwards." "You decide to bring in some more code from the public repo. Here is a 6000 word essay on what rebase means." "You try to look at an old version of the code. Suddenly you are in ‘detached HEAD’ state. The End." I love git, but simple intros like this hide all the confusing complexity and awkward UI that quickly comes to the forefront when using git for everyday work.
推荐用寓言故事来解释Git。
这或许字数太少，不足以阐明Git。我很欣赏Cook女士链接到她网站上更详细的文章。然而，我仍然认为最好的自包含且相对简短的解释是‘The Git Parable’。
js2查看英文原文
This is perhaps too few words to elucidate git. I appreciate that Ms. Cook links to other articles on her own site that go into much greater detail. However, I still think the best self-contained and relatively brief explanation of Git is "The Git Parable."[1] [1] http://tom.preston-werner.com/2009/05/19/the-git-parable.html
用户不应被迫理解工具内部实现，写作应尊重读者背景。
这里完美地说明了为什么我不喜欢使用某些源代码版本控制系统。我不想理解我的源代码控制系统的精确实现，我个人也不认为为了有效使用而必须理解。我意识到这可能是 unpopular opinion，但我挑战你回复理由而不是不可避免地将我踩到 oblivion。我的一个软件开发导师（一位长期从事UNIX OS开发20多年的机械工程师）经常把这个作为他的电子邮件签名，我认为在这个上下文中很贴切：文明通过扩展我们可以不假思索执行的重要操作的数量而进步。话虽如此，我并不主张对版本控制系统‘如何工作’完全无知，我只是觉得‘你必须学习这个系统的内部数据格式和工作原理才能有效使用它’这种哲学有点令人反感。
binarycrusader查看英文原文
And here, perfectly illustrated, is a reminder why I don't like using some source code version control systems. I don't want to understand the precise implementation of my source code control system, and I don't personally believe that I should have to for effective use. I realise this is likely an unpopular opinion, but I would challenge you to reply with justification rather than inevitably downvoting me into oblivion. One of my software development mentors (a long time mechanical engineer who has done UNIX OS development for 20+ years) often has this as his email signature and I think it's rather apt in this context: Civilization advances by extending the number of important operations which we can perform without thinking about them. With that said, I'm not advocating complete ignorance of how a version control system "works", I just find the philosophy of "you must learn the internal data formats and workings of this system to use it effectively" more than a bit distasteful.
视觉指南和示例能帮助读者解决基本困惑。
这是一篇很酷的文章！非常平易近人。有一天我真的很想了解Git的底层，但我对它在如此小的内存占用下做这么多事情感到畏惧。昨晚我和我的小组项目伙伴在使用Git时度过了最艰难的时刻。我以为我们都准备好出门了，结果我们花了又一个半小时瞎搞。Atlassian的可视化指南真的很有帮助：https://www.atlassian.com/git/tutorials/ 对于那些知道所有git命令名称但在基本情境中仍然困惑的人来说，它们很棒，比如‘是merge master吗？Merge origin master？Merge origin/master？为什么它说already-up-to-date？’
bgilroy26查看英文原文
This is a cool essay! It's very approachable. I would really like to understand git under the hood one day, but I'm intimidated by how much it does with such a small memory footprint. My group project partner and I were having the toughest time with git last night. I thought we were all ready to walk out the door and then we ended up monkeying around with it for an hour and a half. The atlassian visual guides really helped: https://www.atlassian.com/git/tutorials/ They're great for people who know the names of all the git commands but who are still thrown off in really basic situations, ie 'Is it merge master? Merge origin master? Merge origin/master? Why does it say already-up-to-date?'
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选