一个明显的答案是“内部维基”。用于软件文档的 wiki 的优缺点是什么？还有其他建议吗？你用什么来做你的软件文档？
Loren Segal - 不幸的是，我们不支持任何 doc 工具来从源代码注释中编译信息，但我同意这将是存储技术文档的最佳方式。我的问题是关于各种文档 - 从系统管理员类型到用户文档。
Svet
问问题
7214 次
8 回答
7
这是一个非常开放的问题，取决于许多因素。
一般来说，如果您使用具有良好文档生成工具的语言（javadoc、doxygen、MS 的 C# 的东西），您应该在您的方法之上编写文档并让您的工具生成页面。优点是您将文本的源代码与代码一起保留，这意味着它在逻辑上正确的位置进行组织，并且在您更改方法的行为时可以轻松编辑。
如果您没有良好的文档工具支持或无法访问源代码，那么 wiki 并不是一个坏主意，但它们是上述方法的第二选择。
注意：我在这里只谈论代码文档。其他工件显然不能与代码一起存储——wiki 是放置这些文档的好地方。或者，如果您使用一些 CMS，您可以简单地将它们docs/作为文本/pdf/任何文件提交到某个文件夹中，以便通过存储库进行编辑。这样做的好处是，如果它被移动，它们会留在存储库中，而 wiki 不会（必要）。
于 2008-09-19T03:55:29.337 回答
3
工具很重要，但不要太拘泥于寻找神奇的工具。我还没有找到任何工具具有“使用微小的隐形精灵神奇地记录所有内容”复选框。:-)
wiki 可以正常工作。或共享点。或谷歌文档。或者您可以使用 SVN 存储库。如果你真的需要的话，你可以用钢笔、信纸和文件柜来做这件事。（我真的不建议这样做！）
最重要的关键是您需要在整个组织中获得支持。在很多商店发生的情况是，他们花费大量时间和金钱在像 Sharepoint 这样的花哨的解决方案上，然后每个人都虔诚地使用它大约两周，然后人们忙于达到最新的里程碑，这是最后一个任何人都听说过。
根据您的组织、领域、您开发的产品类型等，有一些解决方案，但您需要以一种或另一种方式设置系统并使用它。任命某人为官方文档沙皇，给他们一个线索，并告诉他们每次他们说“哦，是的，我将在下周完成记录......”时打他们的头。如果这就是它所需要的。:-)
至于工具……我推荐Atlassian 的Confluence。这是一个很好的 wiki，它被设计为在企业环境中工作，它有很多漂亮的功能，它是可定制的，它与 Atlassian 的一些其他漂亮工具很好地集成，并且基本上是一个非常可靠的产品。
于 2008-09-19T04:58:52.290 回答
2
«软件文档» 是一个非常笼统的术语。有《最终用户文档》、《开发人员文档》、《QA 文档》。第一个通常由合格的技术作家开发。其他的可能是从 wikis、源代码中的文档注释等动态形成的。所有这些东西的维护过程通常非常复杂，每个软件公司都遵循自己的方式。但是所有这些方式都有一个必要的一点：每个代码提交者、架构师、经理、质量保证工程师必须妥善存储每条可能对其他人有帮助的信息。如果需要，其他人必须留意这些件的存储和重新排列件。所有这些步骤都极大地改进了与开发过程相关的所有活动。
于 2008-09-19T04:26:16.893 回答
1
假设您谈论的是代码文档与用户文档，如果您不需要将代码文档分发给组织之外的承包商或合作伙伴，那么内部 wiki 非常有用。
如果您想要可分发的代码文档，Javadoc 或 DOxygen 更合适。
如果您指的是用户文档，您可能需要查看DITA。
于 2008-09-19T03:55:22.833 回答
1
我们目前使用由外部应用程序 (PHP + PhpDocumenter) 以及各种内部 wiki 解析的内联文档。有时它充其量是痛苦的（主要是因为只有一个人更新维基或文档......）
但是，我一直在考虑使用ikiwiki来做内部文档。它与您的源代码控制系统（包括 Git、Subversion、Mercurial、Bazaar、TLA 和 Monotone）集成，因此您的所有文档都可以跟踪您的项目。它是用 Perl 构建的，并具有广泛的插件系统（包括多种标记语言，默认为 Markdown）。此外，源代码控制系统是基于插件的，因此如果您使用的内容没有立即得到支持，您可以添加自己的。如果需要，使用您喜欢的语言，因为它也支持非 perl 插件。
于 2008-09-19T04:01:51.180 回答
1
我开始尝试一种方法来为这些目标做用户文档：
Markdown/Html/Javascript/基于文件的相对链接文档的可移植性（可以在本地文件系统上运行，或者您可以将其放在网络服务器上），内置的屏幕截图处理（交互式调整大小），以及开源以防其他人可能想用疯狂的东西做点什么。
您的文档源是用 Markdown 编写的，并在浏览器运行时通过 Javascript 呈现为 Html。
于 2008-09-19T04:17:30.767 回答
0
我的公司使用各种 Sharepoint 和一个 wiki。Sharepoint 用于特定文档，如需求、演示文稿、合同等，而 wiki 用作帮助指导开发人员存储库，以获取有关使用内部开发库的教程。
于 2008-09-19T03:52:59.483 回答
0
是的，我们使用 wiki，我们也使用 Google 文档。我发现 Google 文档比我尝试过的大多数 wiki 都好，而且，如果您不需要跟踪所有更改，那么您什么也不会丢失。Google docs 提供了一个很好的协作框架。
于 2008-09-19T03:55:28.370 回答