Documentation 存储软件文档的最佳方式是什么？

一个显而易见的答案是“内部维基”。用于软件文档的wiki有哪些优点和缺点？还有其他建议吗？您的软件文档使用的是什么

---

-不幸的是，我们不支持任何文档工具来编译源代码注释中的信息，但我同意这是存储技术文档的最佳方式。我的问题是关于每一种文档，从系统管理员类型到用户文档

我的公司使用各种Sharepoint和wiki。Sharepoint用于特定文档，如需求、演示文稿、合同等，而wiki则用作开发人员存储库的帮助指南，用于提供有关使用内部开发库的教程。

假设您讨论的是代码文档而不是用户文档，如果您不需要将代码的文档分发到组织之外的承包商或合作伙伴，那么内部wiki非常有用

如果您想要可分发的代码文档，Javadoc或DOxygen更合适

---

如果你是指用户文档，你可能想看看。

是的，我们使用wiki，我们也使用谷歌文档。我发现谷歌文档比我尝试过的大多数维基都要好，如果你不需要跟踪所有的变化，你就不会失去任何东西。谷歌文档提供了一个很好的协作框架。

这是一个非常开放的问题，取决于许多因素

一般来说，如果您使用的语言具有良好的文档生成工具（javadoc、doxygen、MS的C#stuff），那么您应该在方法之上编写文档，并让工具生成页面。其优点是将文本源代码与代码放在一起，这意味着文本组织在逻辑正确的位置，并且在更改方法行为时易于编辑

如果您没有良好的文档工具支持或无法访问源代码，那么wiki不是一个坏主意，但它们是上述工具的第二选择

---

注意：这里我只讨论代码文档。其他工件显然不能与代码一起存储——wiki是放置这些文档的好地方。或者，如果您使用一些CMS，您可以简单地将它们提交到一些

docs/

文件夹中，作为text/pdf/任何可通过存储库编辑的文件。这样做的好处是，如果存储库被移动，它们将保留在存储库中，而wiki（不一定）会保留在存储库中。

我们目前使用由外部应用程序（PHP+phpDocument）和各种内部wiki解析的内联文档。有时候，充其量也很痛苦（主要是因为只有一个人更新维基或文档…）

---

但是，我一直在考虑使用来做内部文档。它与您的源代码countrol系统（包括Git、Subversion、Mercurial、Bazaar、TLA和Montone）集成，因此您的所有文档都可以跟踪您的项目。它是用Perl构建的，有一个广泛的插件系统（包括多种标记语言，默认为Markdown）。此外，源代码管理系统是基于插件的，因此如果您使用的东西不立即受支持，您可以添加自己的。如果需要的话，请使用您喜欢的语言，因为它也支持非perl插件。

我开始尝试一种方法来编写用户文档，目标如下：

Markdown/Html/Javascript/基于文件的相对链接文档可移植性（可以在本地文件系统上运行，也可以在Web服务器上运行），内置屏幕截图处理（交互式调整大小），以及开源，以防其他人想用这个疯狂的东西做些什么

您的文档源代码以标记方式编写，并在浏览器运行时通过Javascript呈现为Html

-

---

«软件文档»是一个非常通用的术语。有«最终用户文档»、«开发人员文档»、«QA文档»。第一个通常是由合格的技术作者开发的。其他的可能是通过wiki、源代码的文档注释等动态形成的。所有这些东西的维护过程通常非常复杂，每个软件公司都有自己的方法。但所有这些方法都有一个必要的要点：每个代码提交者、架构师、经理、qa工程师都必须妥善地存储可能对其他人有帮助的每一条信息。其他人必须密切关注这些物品的储存，并在需要时重新安排物品。所有这些步骤大大改进了与开发过程相关的所有活动。

工具很重要，但不要陷入寻找神奇工具的泥潭。我还没有发现一个工具有“用看不见的小精灵神奇地记录一切”勾选框：：-）

维基很好用。或Sharepoint。或者谷歌文档。或者您可以使用SVN存储库。如果你真的需要的话，你可以用钢笔、信纸和文件柜。（我真的不推荐！）

最重要的一个关键是，你需要在整个组织中获得认同。在很多商店里发生的事情是，他们花大量的时间和金钱在一些奇特的解决方案上，比如Sharepoint，然后每个人都虔诚地使用它大约两周，然后人们忙于实现最新的里程碑，这是最后一次有人听说它

根据您的组织、领域、开发的产品类型等，有几种解决方案，但您需要以某种方式建立一个系统并使用它。任命某人为官方文件沙皇，给他们一个俱乐部，并告诉他们每次他们说“哦，是的，我将在下周完成记录……”时都要打人的脑袋。如果是这样的话。：-）

至于工具。。。我推荐亚特兰西亚的。这是一个很好的wiki，它是为在企业环境中工作而设计的，它有很多漂亮的特性，它是可定制的，它与一些