问如何管理开源项目的文档？

EN

我要说的一件事是，文档必须在源代码文件中(使用您想要的任何标记)，然后由这些文档自动生成。

至少在您的站点上，您可以生成格式化的文档下载，作为源代码包的一部分，这样用户就不需要特定的doc工具了。

其他人修复/添加函数，然后编辑/添加与同一文件相邻的一些标记文档的可能性可能很低，但他们在不同文档存储库中找到一个完全不同的文件进行相同操作的可能性略小于零。

如果您想要的话，始终可以有一个包含大量文本块的教程.h，但是将它作为源代码的一部分处理。

如果您的项目是一个库，那么没有什么比javadoc样式的文档更能从代码本身的注释中记录API语法了。

至于有关教程、使用示例等的文档，我强烈建议使用wiki格式。我见过的其他项目有针对不同分支的单独页面。当您启动一个新分支时，您只需将未更改的内容复制到新页面并从那里进行更新。

我推荐wiki的理由是轶事，但来自个人经验。我曾多次为开源项目提供文档更新，但它们都是在wiki上进行的。如果我试图找出一些东西，而文档是误导的或没有帮助的，在我弄清楚之后，我将更新wiki，而我在文档中，它在我的脑海中是新鲜的。如果不是出于一种回馈的感觉，至少因为我知道我可能需要在一两年内自己再查一次。

如果没有wiki，那么进入的障碍就太高了，无论是如何生成文档、存储在哪里、从源代码管理中获取最新的文档、如何编辑、进行实际编辑，还是导航邮件列表以获得补丁的接受。

如果您想要严格控制您的文档，无论如何都要使用最适合您的东西，因为您将是唯一一个更新它的人。如果您想鼓励社区参与，请使用wiki。

与源代码一起托管的标记文件工作得非常好。

例如，基于RST的多卡提尔工具可以从一组文档创建HTML或LaTex (和PDF)。

这个--实际上--结合了你的选项1和选项3。