如何通过编写优秀的文档让未来的自己感到满意

本文简要概述了在开展新项目或旧项目时经常遇到的问题。有时，前期投入一些精力可以节省后续的时间和精力。编写优秀的文档就像是为未来的自己击掌庆祝做好准备✋！我们将通过一个简单的例子和​​一些推荐的实践方法，帮助您开始编写优秀的文档README.md。

斗争

我几乎可以肯定，在你的职业生涯或日常生活中，你曾遇到过让你思考的情况：

“这个问题看起来很眼熟，我肯定以前解决过。可惜我记不起是怎么解决的了！”

尤其从工程角度来看，这种情况非常常见。我们经常会遇到之前遇到过的模式、功能或漏洞，需要我们重复之前的步骤才能解决问题。有时我们愿意再次尝试，所以会继续努力，最终找到解决方案。但有时……

一个例子

我在Hutch领导研发部门，我们经常需要深入研究一些全新的、前所未见的技术、框架或语言。你会尝试很多方法，做很多实验，但不可能记住所有接触过的东西。你可能花几个月时间研究某个东西，完成后就转而研究完全不同的项目。或者，你可能只是在研究流程中的下一个步骤。

然后，在你最意想不到的时候，它发生了。你不得不重新启用三个月前使用的那套框架来做出改变。你一脸困惑地看了看🤔。

“哦，其实我想起来了。要让它这样运行，我到这里……改一下……瞧！”

那一刻你感觉相当不错。你能够回忆起事情的运作方式。你甚至为自己很久以前编写的许多函数都留下了简单的文档而感到自豪。然后，你轻轻点击鼠标，运行项目……

⛔错误！主画面中有一些牛铃指向火星，这是不允许的。

😵 哎呀！这看起来太神秘了。你查看了一下你修改的代码，然后……你又试着运行了一遍。也许某些东西会自动改变。也许再次查看代码会产生某种量子效应。结果并没有。

⛔错误！主画面中有一些牛铃指向火星，这是不允许的。

然后你翻阅评论或文档。但没有任何内容提到这个错误，也没有任何线索指引你正确的方向。这个错误如此独特，你确信自己以前见过，而且也解决过。尽管感觉令人望而生畏，你还是得再次找出答案！

你开始用谷歌搜索这个问题，并注意到一些之前访问过的链接。

“太好了！这个链接可能就是帮我解决错误的关键……呼，危机解除！”

然后你继续向下滚动页面，糟糕！更多……更多访问过的链接。现在你完全不知道哪个链接指向了解决方案（如果有的话）。于是，搜索继续进行，直到最终，你才找到答案——可能要等几分钟、几小时，甚至几天。

好的文档不仅仅涵盖顺利通过的步骤🙂

我为此付出了惨痛的代价，而且不止一次。给函数/方法/类添加文档虽然值得称赞，但往往很容易想当然地认为一切都会正常运行。

我总是尽力让那些研究我代码的人更容易理解。这其中也包括未来的我自己！所以我几乎为所有函数都添加了文档，除了那些无关紧要的函数。正如许多人几十年来一直说的那样：

你的评论应该更多地解释为什么，而不是解释是什么。

你的代码应该具有“自文档性”，这样任何解释“这是什么”的注释都会显得多余。

公平地说，我通常只会在函数很长或者比较复杂的时候，才会给“这是什么”添加注释。添加几行注释就能让我省去逐行检查代码的麻烦。这在很多情况下都帮了我很大的忙，我强烈推荐！

但文档不仅仅是函数上的几行注释。好的文档是精心编写的README.md。在某些情况下，对于大型项目，甚至需要一个功能齐全的专用网站（例如React、Redux、Vue、Slate等）。

文中提到的项目都是开源的。团队基本上有义务提供更详细的说明，帮助用户上手使用他们的框架或库（在这方面他们做得非常出色！）。但是规模较小的私有项目呢？那些只在公司内部运行的项目（无论团队规模大小）呢？还有那些并非纯粹代码相关的问题呢？

我们常常会跳过README.md文件，或者只看几行就草草了事。我一直在实践一种简单却有效的方法，让这项任务不再那么令人畏惧，并帮助我们超越平凡。

创建优秀 README 文件的基本方法

我所说的“理想路径”指的是假设一切都会顺利进行的做法。这意味着我们在处理流程的每个步骤时，都假定它一定会成功。

遗憾的是，情况并非总是如此。那么，我们该如何改善生活？如何确保即使是那些不太顺利的道路也能被覆盖？

以下是一些建议：

• 首先，简要描述一下项目的内容以及你想要解决的问题。这有助于你以及所有参与项目的人员理解项目的意图。

• 在进行所有设置时，请务必将每个步骤添加到文档中README.md。文档格式和措辞不必完美，目前只需记录下来即可。文档通常以安装说明的形式呈现。

• 如果您遇到任何类型的错误，请在页面底部添加一个版块，例如“常见错误”。您可以在这里详细描述您遇到的错误以及您的解决方法。我个人喜欢在这里添加指向解决方案来源（或任何帮助我找到解决方案的资料）的链接。

• 当项目进展到稳定阶段后，我会尝试将其安装在一台新机器上（如果条件允许）。这样做的目的是为了确保我们之前列出的安装步骤正确无误，并且能够按预期运行。

• 最重要的是，你需要添加一个章节来回答这个问题：如何使用/运行这个项目？这部分内容应该尽可能清晰明了，所以请认真对待！不过，有时候你可能要等到项目运行起来之后才能回答这个问题。你可以等到项目处于工作/运行状态时再更新文档README.md。

• 请预留一些时间来检查和整理您的README.md文件。大多数情况下，您可能需要更新它。

对于小型项目来说，这通常就足够了。对于中大型项目，这可以作为制定一些良好实践的起点。与团队其他成员讨论，并达成一个让大家都满意的共识。记住，保持文档更新至关重要！互相监督，在最初的努力之后，它就会像简单的重构一样自然而然地发生！

结论

编写好的文档意味着要保持良好的代码风格README.md，并且更多地记录代码中“为什么”而不是“是什么”。

如果你从小事做起，循序渐进地积累经验，README.md就会发现它并不那么令人畏惧。这不仅会让你未来的生活变得更好，还能帮助其他做出贡献的人。

不要只关注一切顺利的情况，指望所有事情都能成功，还要涵盖可能遇到的错误或新手可能遇到的任何问题。为此，请专门设立一个章节。

额外提示：在与项目经理评估工作量时，请将编写/更新文档所需的工作量考虑在内。不要低估编写优质文档需要花费大量时间这一事实。但这些时间绝对物有所值！

👋 嗨，我是 Gabri！我热爱创新，目前在 Hutch 负责研发工作。我还喜欢 React、JavaScript 和机器学习（以及其他数不胜数的爱好）。你可以在 Twitter 上关注我@gabrielecimato，也可以在 GitHub 上关注我@Gabri3l。如果你有任何其他建议想要分享，欢迎留言；如果你有任何问题，也可以在 Twitter 上私信我！