如何编写好的文档

如果你曾经在休息几天之前只写了一半的软件项目，那么当你重新打开 IDE 时，你会发现这篇文章正是你需要的。

在我领导的技术团队中，我们始终致力于记录所有内容。文档与代码并驾齐驱，同等重要。这有助于确保没有人需要对某个功能的工作原理进行假设，或者召开冗长的会议来了解某个功能。良好的文档为我们节省了大量时间和精力。

也就是说，与普遍认知相反，最有价值的软件文档并非主要为他人编写。正如我在这条广受欢迎的推文中所说：

假期将至，最好提前做好准备，以防万一喝了蛋酒后出现编程瘫痪的情况。（山核桃派和 Python 真是绝配。）🥧🐍

以下是编写优质文档的三个具体步骤，您可以采取这些步骤，以免为时过晚。

1. 从准确的笔记开始

在编写代码的过程中，为了避免遗忘重要细节，最好先做好笔记。虽然之后你可能需要用更详细的文字来解释，但简短的笔记足以记录细节，而不会打断你的编码流程。

在编写代码的同时，打开一个文档，记录你使用的命令、决策和资源等信息。这可以包括：

• 您在终端中输入的命令
• 你为什么选择这种方法而不是另一种？
• 你访问过的帮助链接，或者（咳咳，复制粘贴）灵感
• 你做事的顺序

此时不必担心句子是否完整。只需确保准确记录上下文、相关的代码片段和有用的网址即可。启用任何可用的自动保存选项也很有帮助。

2. 用长篇文字解释决策

完成这一步的最佳时机是当你暂停编码工作，但还没完全放下手头的工作去吃午饭的时候。这样可以确保你在向自己解释时，对相关的背景、想法和决策都记忆犹新。

回顾你之前做的简短笔记，并开始将其扩展成口语化的写作形式。像橡皮鸭一样，把自己想象成在教别人一样，描述你正在做的事情。你可以涵盖以下主题：

• 看似古怪的决定：“我通常会这样做，但我选择做点不一样的事情，因为……”
• 你遇到的挑战以及你是如何克服的
• 支持项目目标的建筑决策

抓住要点。长篇写作并不意味着你会按字数付费！只需使用完整的句子，并像向同事解释你的项目一样写作。毕竟，你是在向未来的自己解释。

3. 不要忽视先决知识

最好在午休时间较长的时候，甚至第二天（但最好不要隔两天）再进行这一步。重新阅读你的文档，并在与项目保持一定距离后，填补任何显而易见的空白。

务必格外注意填写必要的先决知识，或者至少添加链接，尤其是在您经常使用不同语言或工具的情况下。即使是粘贴您使用的 API 文档链接这样的小操作，也能节省您日后数小时的搜索时间。

记录或链接到 README 文件、安装步骤和相关的支持问题。对于经常执行的命令行操作，您可以使用自文档化的 Makefile 文件，man这样每次返回项目时就无需重复执行这些相同的任务。

即使只是短暂地休息一下，也很容易忘记一些细节。这次一定要把所有你觉得有用的信息都记录下来。

记录所有事情

下次当你心想“我肯定会记住这部分，不用写下来”的时候，只需想想这个表情符号：🤦‍♀️

软件项目远不止代码那么简单。为了更好地为未来的成功做好准备，请务必记录所有事项！无论是已建立的流程、基础设施即代码，还是转瞬即逝的未来路线图构想——都记录下来！未来的你会感谢现在的自己。

如果你喜欢这篇文章，请告诉我。欢迎加入victoria.dev ，和成千上万的人一起学习！访问并订阅，了解更多关于提升编程技能的内容。