开源项目流程文档化

2020-09-08 15:50 更新

对于一个项目的维护者来说写文档是最重要的事情之一。

文档不仅说清楚了你的想法是什么,而且还帮助别人在问问题之前理解你需要什么和接下在希望做什么。

将一些东西写下来,当遇到不符合项目预期的内容时,可以轻松的拒绝。同时,它对于人们的参与和提供帮助提供了指导。最有意思的是,撰写文档的人可能永远也不知道是谁读了他写的文档,或者使用项目。

即使你不想长篇大论,对要点略说一二也比啥都不写要好。

写下你的项目的发展方向

请在项目启动时就写下项目目标,并将之加到 README 文件中, 或者创建一个单独的 VISION 文件,其它还能帮助人们了解这方面的信息如项目管理路线图,最好是也把他们公开。

有一个明确的,用文档表达清晰的愿景,能保证项目的走向不会跑偏,同时也能保障因为其他的贡献者增加的奇怪的需求而使项目变质。

比如,@lord 发现项目有一个明确的愿景能够帮助他决定哪个 PR 值得花时间。作为一个维护者的新手,他甚至还后悔当他接到第一个关于 slate ) PR 的时候没有坚持项目本身的原则。

avatar

我一直都在摸索。我没有努力寻求一个完整的解决方案。与其采用那种半吊子办法,我真希望曾经对某些 Issue 的提出者说:”我暂时没有时间干这个,但是我会把他放到我的待办事项中”。

@lord , “开源项目维护者新手的几点技巧”

和大家交流你自己对项目的期望

制定规则是很伤脑筋的。有时候你可能觉得你像是在限制别人的行为或者说把好玩的东西都搞没了。

制定了规则,然后严格执行,当然啦,好的规则会让维护者更轻松。他们会把你从做自己不愿意做的事情中解脱出来。

大多数知道你项目的人对你或者你的处境都是一无所知。他们可能会觉得你做这个项目是有钱拿的,特别是你的项目是他们经常用的而且某种程度上有点依赖的时候。其实你只是在有时候会在项目上花很多时间,但是现在你在忙于新工作或者照顾刚出生的儿子。

这些都是再正常不过的事情!所以确保让别人也知道这些。

如果你维护某个项目是利用空闲时间或者完全自愿的,能花多少时间就花多少时间。而不是你觉得项目需要你花多少时间或者别人想让你花多少时间。

这里是一些值得你写进项目里的东西:

  • 怎样的贡献才会被复查和接受(需要测试吗?提 Issue 有模板吗?
  • 你本人会接受什么类型的贡献?(你是不是只希望在某些部分的代码上需要别人的帮助?
  • 在合适的时候跟进项目(比如说 如果你在七天之内没有收到 maintainer 的回复,而且依旧没有其它任何的响应,那么就直接找 Ta。
  • 你会在这个项目上花多少时间(比如说 “我们每星期只会在这个项目上花5个小时“)

Jekyll CocoaPods 、以及 Homebrew 均是为维护者和贡献者提供了很好的基本规则的项目,乃业内典范。

保证交流是公开进行的

不管是什么时候,保证你的交流是在公共的场所(就是大家都能看到的地方)。如果有人尝试和你私聊,哪怕是讨论一个新的需求或者功能,请礼貌的引导 Ta 到公共的交流场所,比如邮件列表或者 issue tracker。

如果你和别的维护者见面了,或者在私下做了一个很重要的决定,把这些信息告诉大家,即使只是把你的笔记发上去。

这样的话,每个人新加入到你们社区的人和已经呆了多年的人能够了解到的信息是一样的。

以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号