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

Question

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

Loren Segal - 遗憾的是，我们没有任何doc工具支持从源代码注释中编译信息，但我同意这是存储技术文档的最佳方式。我的问题是关于各种文档 - 从sysadmin类型到用户文档。

Answer 1

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

一般来说，如果您使用的语言具有良好的文档生成工具（javadoc，doxygen，MS的C＃内容），您应该将文档编写在方法之上，并让您的工具生成页面。优点是您可以将文本的源与代码保持在一起，这意味着它在逻辑上正确的位置进行了组织，并且在您对方法的行为进行更改时可以轻松编辑。

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

注意：我这里只讨论代码文档。其他工件显然不能与代码一起存储 - 维基是放置这些文档的好地方。或者，如果您使用某些CMS，您只需将它们作为text / pdf /通过存储库可以编辑的文件提交到某个docs/文件夹中。这样做的好处是，如果移动存储库，它们会保留在存储库中，而wiki则不会（必然）。

Answer 2

工具很重要，但在寻找神奇工具时不会陷入困境。我发现的工具还没有“使用微小的隐形精灵神奇记录所有东西”的复选框。 ： - ）

维基将正常工作。或者Sharepoint。或Google文档。或者您可以使用SVN存储库。如果你真的需要的话，你可以用钢笔，便条纸和文件柜做到这一点。 （我真的不推荐！）

最重要的关键是你需要在整个组织中获得支持。在许多商店中发生的事情是他们花费大量时间和金钱在像Sharepoint这样的奇特解决方案上，然后每个人都虔诚地使用它大约两周，然后人们忙着打最新的里程碑，这是最后一个任何人都听说过。

根据您的组织，领域，您开发的产品类型等，有一些解决方案，但您需要设置一个系统并使用它。任命某人为官方文件沙皇，给他们一个cluebat，并告诉他们每当他们说“哦，是的，我将完成下周的记录......”时会打人。如果这是它需要的。 ： - ）

至于工具......我建议Atlassian提出Confluence。它是一个很好的维基，它设计用于企业环境，它有很多漂亮的功能，它可以自定义，它与Atlassian的其他一些漂亮的工具很好地集成，基本上是一个非常可靠的产品。

Answer 3

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

Answer 4

假设您正在讨论代码文档与用户文档，如果您不需要将组织外部代码的文档分发给承包商或合作伙伴，则内部Wiki非常有用。

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

如果您指的是用户文档，您可能需要查看DITA。

Answer 5

我们目前使用由外部应用程序（PHP + PhpDocumenter）解析的内联文档以及各种内部wiki。有时它最多是痛苦的（主要是因为只有一个人更新维基或文档...）

但是，我一直在考虑使用ikiwiki来制作内部文档。它与您的源控制系统（包括Git，Subversion，Mercurial，Bazaar，TLA和Monotone）集成，因此您的所有文档都跟踪您的项目。它内置在Perl中，并具有广泛的插件系统（包括多种标记语言，默认为Markdown）。此外，源代码控制系统是基于插件的，因此如果您使用的内容不能立即支持，您可以添加自己的。在您的首选语言中，如果需要，因为它也支持非perl插件。

Answer 6

我开始尝试使用这些目标来完成用户文档的方法：

基于Markdown / Html / Javascript /文件的相对链接文档的可移植性（可以在本地文件系统上运行，或者您可以将其放在网络服务器上），内置 - 处理屏幕截图（交互式调整大小）和开源，以防其他人可能想要做一些疯狂的事情。

您的文档源是用Markdown编写的，并在浏览器运行时通过Javascript呈现给Html。

  

Mandown - http://wittman.org/mandown/

Answer 7

我公司使用各种Sharepoint和wiki。针对特定文档（如需求，演示文稿，合同等）的Sharepoint，而wiki用作帮助指导开发人员存储库以获取有关使用内部开发库的教程。

Answer 8

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