2021-26: 设计文档的实践
内容提要
本文讨论了go-storage项目设计文档的写作实践，经历了从自娱自乐到缺乏反馈的低谷，最终建立了规范的讨论和提案流程。团队通过提案（GSP）和问题跟踪，逐步形成了有效的文档体系。
关键要点
-
讨论go-storage项目设计文档的写作实践。
-
go-storage的设计文档经历了三个阶段：自娱自乐、自暴自弃、像模像样。
-
自娱自乐阶段：设计文档主要是为个人理清思路，避免过早陷入实现细节。
-
自暴自弃阶段：缺乏反馈导致写文档的热情下降，认为写文档是浪费时间。
-
像模像样阶段：团队建立了基于提案的讨论和推进实现的体系。
-
提出想法后，写RFC（GSP），并使用PR编号避免冲突。
-
RFC被批准后，创建跟踪问题以跟踪实现进度。
-
RFCs从独立的specs repo拆分到各个项目内部，由项目维护者进行审核。
延伸解读
设计文档的重要性
设计文档不仅是项目的记录，更是团队沟通的桥梁。通过规范的文档流程，团队成员可以更清晰地理解项目目标和实现细节，避免因信息不对称而导致的误解和重复工作。
阶段性演变的教训
go-storage项目的设计文档经历了三个阶段，反映了团队在文档管理上的成长。自娱自乐阶段虽然有助于个人思考，但缺乏反馈的自暴自弃阶段则提醒我们，持续的沟通和反馈是文档有效性的关键。
提案与反馈机制
建立基于提案的讨论机制后，团队能够有效收集反馈并推动项目进展。通过RFC（GSP）的方式，团队不仅能系统化地记录想法，还能确保每个提案都经过审查，提升了文档的质量和可追溯性。
延伸问答
go-storage项目的设计文档经历了哪些阶段？
go-storage项目的设计文档经历了自娱自乐、自暴自弃和像模像样三个阶段。
在自娱自乐阶段，设计文档的主要目的是什么？
在自娱自乐阶段，设计文档主要是为个人理清思路，避免过早陷入实现细节。
自暴自弃阶段对设计文档的影响是什么？
自暴自弃阶段导致缺乏反馈，写文档的热情下降，认为写文档是浪费时间，造成了混乱。
团队是如何建立有效的设计文档讨论体系的？
团队通过提案（GSP）和问题跟踪，建立了基于提案的讨论和推进实现的体系。
RFC（GSP）在设计文档中起到什么作用？
RFC（GSP）用于提出想法并在得到反馈后进行详细设计，帮助团队推进实现。
如何跟踪RFC的实现进度？
在RFC被批准后，会创建跟踪问题以跟踪实现进度。
