如何编写好的文档

2020年12月30日10:50:04 发表评论 37 次浏览

本文概述

在本文中, 我将分三步讨论永不忘记项目工作原理的秘密。

如果你在休息几天之前写了一半的软件项目, 那么当你重新打开该IDE时, 会发现本文是你所需要的。

您在星期五(完成的拼图)与星期一(一大堆拼图)的项目漫画

不用担心, 所有这些都将在星期五再次聚在一起……(作者漫画)

在我领导的技术团队中, 我们一直在努力记录所有事情。文档是代码的平等参与者。

这有助于确保没有人需要对某事物的工作原理进行假设, 也无需召集长时间的会议来获得该功能的工作知识。好的文档可以为我们节省很多时间和麻烦。

就是说, 与普遍看法相反, 最有价值的软件文档并不是主要为其他人编写的。正如我在这个广受欢迎的推文中所说的:

好的文档的秘诀是在编写代码时编写它。你是你的第一批观众。向你说明自己在做什么。将来你会谢谢你的!

-维多利亚·德雷克(Victoria Drake)2020年11月24日

你可以采取以下三个具体步骤来编写优质的文档, 以免为时已晚。

1.从准确的笔记开始

在用代码制定想法时, 请确保从头开始编写准确的注释, 以免很快忘记重要的细节。虽然稍后你将要以长篇幅形式对自己进行解释, 但是简短形式的注释将足以捕获细节而不会中断你的编码会话流程。

在文档旁边打开文档, 并写下诸如命令, 决策和使用的源之类的内容。这可以包括:

  • 你输入的终端命令
  • 为什么选择特定方法而不是其他方法
  • 你访问过的链接以获得帮助或咳嗽复制粘贴咳嗽灵感
  • 你做事的顺序

现在不用担心完整的句子。只需确保你准确捕获上下文, 相关的代码段和有用的URL。打开任何可用的自动保存选项也可能很有帮助。

2.详尽解释决策

解决此步骤的理想时间是你暂时停止编码, 但是在你完全不吃午餐之前, 你正在做什么。

当你向自己解释时, 你想确保上下文, 构想和决定仍然牢记在心。

翻阅你所记的简短笔记, 然后开始将其扩展为会话式写作。做自己的橡皮鸭。描述你在做什么, 就好像你正在教别人。你可能会涉及以下主题:

  • 看起来古怪的决定:"我通常会这样做, 但是我选择做一些不同的事情, 因为……"
  • 你遇到的挑战以及如何克服挑战
  • 支持你的项目目标的架构决策

坚持要点。冗长的写作并不意味着你会被单词所吸引!只需使用完整的句子, 然后写就好像向同事解释你的项目一样。毕竟, 你是在向未来解释。

3.不要忽略先决条件知识

最好在长时间的午餐休息后或第二天(但可能不是两天)之后执行此步骤。重新阅读你的文档并填写在你自己与项目之间保持一定距离后显而易见的空白。

请特别注意填写或至少链接到先决条件知识, 尤其是如果你经常使用其他语言或工具时。即使是粘贴到你使用的API文档的链接中的小动作也可以节省以后的搜索时间。

写下或链接到自述文件, 安装步骤和相关的支持问题。对于经常执行的命令行操作, 你可以使用自记录的Makefile避免必须人每次回到项目时的常见任务。

即使只是短暂的项目休息, 也很容易忘记支持细节。捕获这次发现有帮助的所有内容。

记录所有东西!

下次当你想起"我相信我会记住这部分, 无需写下来"时, 只需回想一下以下表情符号即可:🤦♀️

软件项目不仅包含代码, 还包含许多其他内容。为了最好地建立自己的未来自我, 取得成功, 请记录所有事情!无论是你已经建立的流程, 基础架构即代码, 还是日新月异的路线图, 请写下来!将来你会为此而感激的。

如果你喜欢这篇文章, 我很想知道。加入与我一起学习的数千人victoria.dev!访问并订阅有关构建你的编码技能堆栈的更多信息。

一盏木

发表评论

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen: