编写文档

by Gabriele Cimato

加布里埃莱·西马托(Gabriele Cimato)

如何通过编写优质文档来使自己的未来快乐 (How to make your future self happy by writing good docs)

或者，在清除旧代码库时如何减少痛苦 (Or how to be less miserable when dusting off an old code base)

This is a little overview of common problems faced when working on a new or old project. Sometimes making a little effort up front can save you time and energy down the line. Writing good docs is like getting ready for your future self to high-five you ✋! We’ll see a silly example and a few recommended practices to get started with a good README.md.

这是在处理新项目或旧项目时遇到的常见问题的概述。 有时候，在前端做些努力可以节省您的时间和精力。 编写好的文档就像为未来的自我做好准备，使自己高五岁！ 我们将看到一个愚蠢的示例和一些推荐的实践，以从一个好的README.md开始。

奋斗 (The Struggle)

I’m almost certain that in your career, or in your everyday life, you faced a situation before that makes you think:

我几乎可以肯定的是，在您的职业生涯或日常生活中，您已经遇到了一种情况，然后才想到：

“This problem looks familiar, I’m pretty sure I solved it before. If only I could remember how I did it!”

“这个问题看起来很熟悉，我很确定之前已经解决了。 如果我能记得我是怎么做到的！”

Especially coming from an engineering perspective this happens quite a lot. Repeated patterns, functions or bugs we’ve met before that require us to go through the exact same past effort to overcome an issue. Sometimes we are willing to do it again, so we go ahead and figure it out once more. Some other times though…

特别是从工程角度来看，这种情况经常发生。 在此之前，我们反复遇到的模式，功能或错误要求我们经历与过去完全相同的努力来解决问题。 有时我们愿意再做一次，因此我们继续进行尝试。 不过其他时候…

一个例子 (An example)

I lead the R&D department at Hutch and we often have to dig deep into new and unseen technologies, frameworks or languages. You try and experiment a lot and can’t expect to remember everything you interact with. You work on something for a couple months then, once you’re done, switch to something very different. Or maybe you just work on the next step in a pipeline.

我领导Hutch的研发部门，我们经常不得不深入研究新的和看不见的技术，框架或语言。 您尝试和尝试了很多，无法期望记住与之互动的一切。 您需要工作几个月，然后一旦完成，就切换到非常不同的东西。 或者，也许您只是在进行下一步。

Then, when you least expect it, it happens. You have to go back to that framework you used 3 months before to make a change. You give it a look, a puzzled one ?.

然后，当您最不期望时，它就会发生。 您必须回到3个月前进行更改的框架。 您看一下，不解？

“Oh, actually I remember this. To make it behave this other way I go here…change this…and voilà!”

“哦，实际上我记得这一点。 为了使其表现出其他方式，我去了这里……改变这个……瞧瞧！”

At that moment you feel pretty good about it. You were able to recollect how things worked. You’re even proud of yourself for leaving simple docs on many of the functions you wrote many moons before. Then with a light touch of your mouse, you run the project and…

那一刻，您对此感觉很好。 您能够回忆起事情如何进行。 您甚至为自己之前编写过许多卫星的许多函数保留了简单的文档而感到自豪。 然后轻轻一按鼠标，即可运行该项目并…

⛔ ERROR! The main frame has some cowbells directed towards Mars, this is not allowed.

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

? Yikes! This looks very cryptic. You take a look at the code you changed and, well…you try to run it again. Maybe something will automatically change. Maybe looking at it again had some quantum effect of some sort. Nope.

？ kes！ 这看起来很神秘。 您看一下更改的代码，然后……尝试再次运行它。 也许某些事情会自动改变。 也许再次看它会产生某种量子效应。 不。

⛔ ERROR! The main frame has some cowbells directed towards Mars, this is not allowed.

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

You then read through the comments or the docs. Nothing mentions this error, nothing points you in the right direction. This error is so distinctive that you’re sure you saw it before, and also solved it before. As daunting as it feels, you have to figure it out…again!

然后，您通读注释或文档。 没有任何提及此错误的内容，没有任何内容指示您正确的方向。 此错误是如此独特，以至于您确定您之前已经看过它，并且之前也已解决了它。 感觉令人生畏，您必须再次弄清楚！

You start googling the problem and notice some previously visited links.

您开始搜索问题，并注意到一些以前访问的链接。

“Great! This link is probably the one that helped me with the error…phew. Crisis averted!”

“大！ 此链接可能是帮助我解决错误的那个……phe。 避免了危机！”

You then scroll the page and, oh no! More…many more visited links. So now you have no idea which one led to a solution if any. And so the search continues until eventually, you figure it out — minutes, hours or even days later.

然后，您滚动页面，哦，不！ 更多…更多访问的链接。 因此，您现在不知道哪个人导致了解决方案(如果有)。 因此搜索一直持续到最终您找到答案-几分钟，几小时甚至几天之后。

好的文档不仅涵盖了幸福的道路？ (Good documentation covers more than just happy paths ?)

I learned this the hard way. Multiple times. It’s often easy, although admirable, to add docs to your functions/methods/classes with the assumption that everything will work well.

我经过惨痛的教训才学到这个。 多次。 假设一切都会正常运行，将文档添加到函数/方法/类通常很容易，尽管令人钦佩。

I always try to make life easier for whoever will dig into my code. That includes future me! So I diligently add docs to almost all of my functions but the trivial ones. As many have said for decades:

我总是尽力使那些深入研究我的代码的人更加轻松。 这包括未来的我！ 因此，我努力地将文档添加到几乎所有函数中，但琐碎的函数中。 几十年来，许多人都说过：

Your comments should explain the why more than the what.

您的评论应该解释为什么比什么更多。

Your code should be “self-documenting” so that any added comment addressing the “what” would result redundant.

您的代码应该是“ 自我记录的”，以便添加任何涉及“内容”的注释将导致重复。

In all fairness, I tend to add comments even for the “what”, only when I know a function is either long or somehow intricate. Adding a few lines of comments would allow me to skip examining every line of code. This has been helpful countless times and I absolutely recommend it!

公平地说，只有当我知道某个函数很长或某种程度上错综复杂时，我才倾向于为“什么”添加注释。 添加几行注释将使我跳过检查每一行代码。 这对无数次都是有帮助的，我绝对推荐！

But documentation is not just lines of comments on a function. Good documentation is a well written README.md. In some scenarios even a full-fledged dedicated website for bigger projects (see React, Redux, Vue, Slate, …).

但是文档不仅仅是函数的注释行。 好的文档是写得很好的README.md 。 在某些情况下，甚至是用于大型项目的成熟专用网站(请参见React ， Redux ， Vue ， Slate等等)。

The projects mentioned are all open source. Teams are basically compelled to go in greater detail to help people start using their framework or library (and have been doing a great job in that regard!). But what about smaller private projects? What about those projects that will only live within the company (no matter what the size of the team is)? And what about all those issues that are not purely code related?

提到的项目都是开源的。 基本上，团队不得不更加详细地帮助人们开始使用他们的框架或库(并且在这方面做得很好！)。 但是，较小的私人项目呢？ 那些仅存在于公司内部的项目又如何呢(无论团队的规模如何)？ 那么那些与代码不完全相关的问题呢？

More often than not we tend to skip the README.md file or dismiss it with a few lines only. I’ve been following a simple yet powerful practice to make this task less intimidating and help go beyond the happy paths.

通常，我们倾向于跳过README.md文件或仅用几行就将其关闭。 我一直在遵循一个简单而强大的实践，以使此任务减少威吓性，并帮助他们走出幸福的道路。

创建良好自述文件的基本方法 (A basic approach to creating a good README)

When mentioning “happy paths” I refer to the practice of assuming everything will run smoothly. This means we are only addressing each step of a process as if it will always succeed.

当提到“快乐的道路”时，我指的是假设一切都会顺利进行的做法。 这意味着我们只是在处理流程的每个步骤，就像它总是会成功一样。

Unfortunately, that is not always the case so, how can we make our lives better? How do we make sure that even the not-so-happy paths are covered?

不幸的是，情况并非总是如此，我们如何才能改善我们的生活？ 我们如何确保即使不是很幸福的道路也能被覆盖？

Here are a few suggestions:

这里有一些建议：

• Start by writing down a few lines about what the project is about and what problem you are trying to solve. This helps you, and whoever goes through it, understanding the intent of the project.

  首先写下几行有关项目的内容以及您要解决的问题的内容。 这样可以帮助您以及所有通过的人员了解项目的意图。

• As you go about setting everything up, make sure you add each step to the README.md. It doesn’t have to be well formatted and phrased, it just needs to be there for now. This usually comes in the form of installation instructions.

  README.md所有设置时，请确保将每个步骤添加到README.md 。 它不必格式和措辞都很好，只需要暂时存在即可。 这通常以安装说明的形式出现。

• If at any time you face an error of any sort, add a section at the bottom. You can call it Common Errors. There you add some details about the error you faced and how you solved it. One crucial thing I like to do here is add links to the source of the solution (or anything that helped me get there).

  如果您随时遇到任何错误，请在底部添加一个部分。 您可以将其称为“ 常见错误”。 在此处，您将添加一些有关所遇到的错误以及如何解决该错误的详细信息。 我想在这里做的一件至关重要的事情是添加指向解决方案源的链接(或任何有助于我到达那里的东西)。

• When I reach a stable point in the project I try to install it on a new machine (if it’s a possibility). The goal here is to ensure that the set-up steps we listed before are correct and work as expected.

  当我在项目中达到稳定点时，我尝试将其安装在新计算机上(如果可能)。 此处的目标是确保我们前面列出的设置步骤正确无误，并能按预期进行。

• Most importantly, you need to have a section answering the question: how do I use/run this project? This should be as clear as possible, so put some effort into it! Sometimes, though, you can’t answer this question until later on. You can wait until you are in a working/running state to update the README.md .

  最重要的是，您需要有一个部分来回答以下问题： 我如何使用/运行该项目？ 这应该尽可能清楚，所以要花点力气！ 不过，有时候，您直到稍后才能回答这个问题。 您可以等到处于工作/运行状态来更新README.md 。

• Put aside some time to review and clean up your README.md file. Most of the time you’ll probably need to update it.

  留出一些时间来检查和清理您的README.md文件。 大多数时候，您可能需要更新它 。

This is often enough for small size projects. For mid to large-sized ones it can be a starting point to develop some good practices. Talk about it with the rest of the team and agree on a common approach that will make everyone happy. Keep in mind that maintaining the docs up to date is crucial! Hold each other accountable for it and after the initial effort, it’ll become natural, just like a simple refactoring!

对于小型项目，这通常就足够了。 对于中大型企业，这可能是发展一些良好做法的起点。 与团队的其他成员讨论此事，并商定一种使每个人都高兴的通用方法。 请记住， 保持文档最新是至关重要的！ 让彼此负责，经过最初的努力，就像简单的重构一样，它会变得自然！

结论 (Conclusion)

Writing good docs involves maintaining a good README.md and documenting the whys in your code more than the what.

编写良好的文档，不仅要维持良好的README.md并在代码中记录了个为什么比什么更多。

If you make a small effort and incrementally build up a good README.md it will feel less intimidating. Not only will it make your life better in the future, but it will help anyone else contributing.

如果您付出很小的努力，并逐步建立起良好的README.md它的威胁README.md就会减少。 它不仅可以改善您的生活，而且可以帮助其他人做出贡献。

Don’t cover only the happy paths expecting everything will work, also cover eventual errors that you face or any issue a newcomer might face. Keep a dedicated section for this.

不要只涵盖期望一切正常的快乐道路，还不能涵盖您遇到的最终错误或新手可能遇到的任何问题。 为此，请保留专用部分。

Bonus: when estimating your work with a PM, take into account the effort required to write/update the docs. Don’t underestimate the fact that good docs require a good amount of time. But that time is very well spent!

奖励：在评估PM的工作时，请考虑编写/更新文档所需的工作。 不要低估优质文档需要大量时间的事实。 但是那段时间花得很好！

? Hi, I’m Gabri! I love innovation and lead R&D at Hutch. I also love React, Javascript and Machine Learning (among a million other things). You can follow me on twitter @GabriOnTheRocks and on GitHub @Gabri3l . Leave a comment if you have any other recommendation that you’d like to share, or send a DM on Twitter if you have any question!

？ 嗨，我是加布里！ 我热爱创新，并领导Hutch的研发工作。 我还喜欢React，Javascript和机器学习(还有其他一百万种东西)。 您可以在twitter @ G abriOnTheRocks和GitHub @ Gabri3l上关注我。 如果您有其他要分享的建议，请发表评论，如果有任何疑问，请在Twitter上发送DM！

翻译自: https://www.freecodecamp.org/news/how-to-make-your-future-self-happy-by-writing-good-docs-f41fba2d2dab/

编写文档