存储软件文档的最佳方式是什么？ [英] What is the best way to store software documentation?

问题描述

一个明显的答案是内部维基。用于软件文档的wiki有哪些优点和缺点？任何其他建议？您在软件文档中使用什么？

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

解决方案

这是一个非常开放的问题，取决于很多因素。一般来说，如果您使用的语言具有良好的文档生成工具（javadoc，doxygen，MS的C＃内容），则应将文档写在您的方法之上，并让您的工具生成页面。优点在于，您将文本的源与代码保持一致，这意味着在逻辑上正确的位置进行编排，并且可以在对方法的行为进行更改时轻松编辑。

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

注意：我仅在谈论代码文档。其他文物显然不能与代码一起存储 - 维基是放置这些文档的好地方。或者，如果您使用某些CMS，您可以简单地将它们以一些 docs / 文件夹作为文本/ pdf /任何可通过存储库进行编辑的文件提交。它的优点是，如果它被移动，它们将保留在存储库中，而wiki不会（必然）。

An obvious answer is "an internal wiki". What are the pros and cons of a wiki used for software documentation? Any other suggestions? What are you using for your software documentation?

Loren Segal - Unfortunately we don't have support for any doc tool to compile information from the source code comments but I agree it would be the best way to store technical documentation. My question was about every kind of documentation tho - from sysadmin type to user documentation.

解决方案

That's a very open ended question, and depends on many factors.

Generally speaking, if you use a language that has good documentation generation tools (javadoc, doxygen, MS's C# stuff), you should write your documentation above your methods and have your tools generate the pages. The advantage is that you keep the source of your text alongside your code which means it is orgnanized in the logically correct place and easily editable when you make a change to the behaviour of the method.

If you don't have good doc tool support or don't have access to source code, wiki's aren't a bad idea, but they're a second choice to the above.

Note: I'm talking only about code documentation here. Other artifacts obviously cannot be stored alongside code-- a wiki is a great place to put those documents. Alternatively if you use some CMS you can simply commit them in some docs/ folder as text/pdf/whatever files to be editable via the repository. The advantage there is that they stay with the repository if it is moved whereas a wiki does not (necessarily).

这篇关于存储软件文档的最佳方式是什么？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！