建议不要用issue做文档

[cssmagic]

建议不要用issue做文档

[cssmagic]

是的，我在本地写文档时是在 /doc 目录下写 *.md 的，不过只是作为我自己的书写环境和存档，不会 push 到 origin。用 Issue 写文档也确实有不妥的地方，但考虑到以下一些原因，我还是这样做了。

• 我是个优柔寡断的人，文档结构或措辞会频繁修改，放在代码库里更新不方便。（虽然除我以外的人看不到修改过程，但这似乎不重要。）
• Issue 是永久链接，而代码库里的 *.md 则未必（文件名或目录结构可能会改）。
• Issue 可评论可交互。这一点真的太重要了！看文档看到不爽，可以立即吐槽，这种便利在我看来是压倒一切的优势。这也是我不用 Wiki 写文档的原因。
• 放在代码库里似乎会方便其它开发者看文档，并帮助修改文档。但我估计大多数对这个项目感兴趣的人只是 bower install 一下拿来用，看文档已是奢求，帮助写文档几乎不可能。如果真的有人愿意帮助完善文档，直接在 Issue 下面评论也比 PR 要便利太多了。

由于这个项目的规模有限，用 Issue 写文档的缺陷还不是那么明显。看到 Seajs 现在还在用 Issue 写文档，我也就安心了。

当然对于有一定规模的项目，我还是会用公开的 repo 来组织文档。比如 CMUI/demo 和 CMUI/doc。

[cssmagic]

我很想开发一个工具，把本地的 *.md 文件同步到指定的 Issue 中。不知道有没有现成的方案？

[hax]

不知道啊。要实现的话也不是特别复杂，有现成的github api可以读写issue。

[cssmagic]

当然对于有一定规模的项目，我还是会用公开的 repo 来组织文档。比如 CMUI/demo 和 CMUI/doc。

具体怎么组织文档我还没想好，估计最后多半还是会采用 Issue 来发布。我现在还没有概念，只能在实践中慢慢摸索和体会了。

[cssmagic]

我后来发现两者不矛盾——可以把文档的源文件存在 repo 里，然后只对外公布 issue 形式的文档。

[hax]

不过这需要你手动维护啊。

[cssmagic]

对，所以我需要写个工具帮我自动同步。