John | 曲

Reflection in Transition

贝贝60秒:好文档是尊重大家

曲政 / 2019-05-18


今天是贝贝报告给你的第 79 天
2019-05-18 星期六

今天的目标是发布 Tetracamthon 项目到 FreeCAD 论坛,但是我却没发布,有三点理由。

第一,文档结构尚不完整。四个类型既然分了独立的文件夹,就应该有各自的 README 和 _sidebar 文件,不能借用上层,也不能互相雷同。

第二,能呈现的还没写完。我整理了一上午,除了四篇雷同的 README,只写了一篇 Resource 文件夹的 README,把两篇 60 秒的中文转入了 How-to。我至少还有“机构定义”、“机器沿革”、“数据来源”和“相位分析”,等几篇文章可以写。

第三,我自己不想看这些文档。将心比心,如果读到这种程度的文档,我不会关注,因为没有激起“我”的兴趣。即使作者是我的朋友,我却不知道如何帮忙,因为没有明确的行动清单。如果将来项目更新再次进入我的视野,我也不会凑近去看,因为第一印象不好。

我的目的是请朋友行动,让内行关注,给外行留下好印象。写好文档,是对大家的尊重。