知识卡片

普通读书笔记卡 · 5451.c.1

三层文档结构对应社区三种角色

理解等级:未标注

真正成功的开源项目通常都有三个层次分明、用途各不相同的文档,虽然不同项目对它们的具体命名或组织方式不尽相同,但结构基本一致。第一层是README,回答”这个项目是干什么的、谁参与了这个项目”,帮助一个陌生人判断要不要成为这个项目的用户。第二层是安装/使用说明,告诉你如何安装、运行时需要哪些依赖,通常不会事无巨细地记录每个细节,而是给出一条”通常可以按下列方式入手使用”的清晰路径,帮助一个已经决定尝试的人真正顺利地成为用户。第三层是贡献者信息,说明人们应该如何自己构建新版本的软件、需要哪些依赖、如何贡献代码,帮助一个已经在用的用户进一步成长为项目的贡献者。这三层文档之所以要严格区分,是因为它们精准对应着社区里三类完全不同的人(潜在用户、已上手用户、潜在贡献者),任何一层缺失或者三层混在一起写,都会让某一类人找不到自己真正需要的信息——这也解释了为什么很多企业内部项目的文档写得再详细,新人依然找不到构建方法:因为文档往往没有区分”我该不该用这个”和”我该怎么用这个”和”我该怎么参与开发这个”这三个完全不同的问题。

这张卡片看不懂?

已有反馈 · 0 / 10 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 1 处

    参考来源

    - 位置:《团队之美》第8章《内部开源》(Auke Jilderda访谈录,源文件:pzm_ch08.txt) - 结论依据:原文明确列出README、使用说明、贡献者信息三个层次的文档及其分别对应的用户、贡献者、代码提交者三种角色,并说明README帮人决定是否成为用户、安装信息帮人成为用户、贡献者信息帮用户成为贡献者的具体作用,直接支撑本卡片结论。 - 原始内容:真正成功的开源项目通常有三个层次截然不同的文档……第一个是README:项目是干什么的,谁参与了项目。第二个层次是如何使用……第三个层次是贡献者信息……注意这符合社区中三种完全不同的人:用户、项目贡献者、代码提交者。