如何编写更好的文档

好文档的秘诀就是在你写代码的时候就把它写出来。你是你的第一个听众。向自己解释你在做什么。未来的你会感谢你自己!

 

这里有三个具体步骤,你可以趁早写好文档。

 

1. 从准确的笔记开始

当你在代码中提出想法时,通过从准确的笔记开始,确保你不会很快忘记重要的细节。虽然你以后会想用长篇的形式向自己解释一些事情,但短篇的笔记就足以捕捉细节,而不会打断你的编码会话流程。

在你的代码旁边打开一个文档,写下你使用的命令、决定和来源等内容。这可以包括

你输入的终端命令

为什么您选择了一种特定的方法而不是另一种方法

您所访问的链接,以帮助或咳嗽复制-粘贴咳嗽的灵感。

你做事情的顺序

此时不要担心完整的句子。只要确保你准确地捕捉上下文,相关的代码片段和有用的URL。开启任何可用的自动保存选项也会很有帮助。

2. 用详细的描述解释决定

做决定很简单,但是如何做这样的决定,需要发掘更多的原因和动机,如果你文档写的更详细,那么天长日久之后,你会回忆起当初的设计.

处理这一步的理想时间是当你从编码中休息的时候,但在你完全出去吃午饭之前,不管你此刻正在做的是什么。

你要确保当你向自己解释时,背景、想法和决定都还在脑海里。

翻阅你所做的短篇笔记,并开始将它们扩展为对话式写作。做你自己的橡皮鸭。描述你正在做的事情,就像你在教别人一样。你可能会涉及到以下主题。

怪模怪样的决定。"我通常会这样做,但我选择做一些不同的事情,因为..."

您遇到的挑战以及您如何克服这些挑战。

支持您项目目标的建筑决策

坚持写要点。长篇大论的写作并不意味着你会按字数付费! 只要用完整的句子,写得像向同事解释你的项目一样。毕竟你是在向未来的你解释。

3. 不要忽视先决知识

这一步最好在长时间的午休后,甚至第二天(但可能不是两天)完成。重新阅读你的文档,并在你和项目之间保持一定距离后,填补任何变得明显的空白。

要特别注意填写或至少链接到先决知识,尤其是当你经常使用不同的语言或工具时。即使是粘贴一个你使用的API文档的链接这样的小动作,也可以节省未来几个小时的搜索时间。

写下或链接到README、安装步骤和相关支持问题。对于经常执行的命令行操作,你可以使用一个自带文档的Makefile,以避免每次回到项目时都要处理常见的任务。

即使只是短暂地离开项目,也很容易忘记支持细节。捕捉你这次发现的任何有用的东西。

把所有的事情都记录下来!

下一次,当你发现自己在想:"我肯定会记得这部分的,没必要写下来。"只要回忆一下这个表情:♀️。

记得订正文档的问题,时常勘误

我读过很多的文档, 印象最深刻的是文档过期, 跟事实不尽相符, 很多参数,代码,都陈旧不堪. 如果你不时常订正, 那么你留下来的也不是一个好的文档.

软件项目是由很多东西组成的,不仅仅是他们的代码。为了给未来的自己最好的准备,把所有的东西都记录下来! 无论是你建立的流程、基础设施及代码,还是昙花一现的未来路线图想法--把它写下来! 未来的你会为此感谢你。

 
 

分类: 个人 标签: 文档 发布于: 2020-12-26 19:48:34, 点击数: