用什么工具编写文档？
用什么工具编写文档？
具体为
- 用户文档
- 系统pipe理
- 发展
我正在寻找软件如MS Word，维基，TeX（LaTeX，LyX）和自动化工具。
我使用Mark Overdown编写了与Stack Overflow相同的格式化语法。 由于文档是纯文本，所以它们可以在版本控制中与代码一起生活。 这很有用。
我用瑞士军刀Pandoc把文件呈现给HTML和PDF。 用一个简短的样式表，这些看起来比文字处理器的文档更好。
如果我们在谈论技术文档，在我看来有两种不同的文档，其中你应该有两种文档。 对于库和API，自动生成的文档描述了可用于参考的函数调用和types，但是您还需要可从顶部到底部阅读的有用的用户指南/教程样式文档：
- Pandoc针对黑客的低级API参考
- Pandoc 用户指南 （和黑客）
附录 ：您可以使用狮身人面像这两种文件。 输出很漂亮
我最近发现了Explain博士 ，这对创build用户界面文档非常有用。 它会将所有用户界面元素（button，菜单项，编辑框等）从正在运行的应用程序中分离出来，然后从中提取所有可能的元信息以启动文档（请参阅屏幕快照）。 然后，您只需删除或调整find的项目并编辑说明即可。 非常快速地生成真正专业的用户界面文档。 它还具有您所期望的所有其他最终用户帮助文档function。
这个屏幕截图显示了它为你创build的一个图像。 这是通过指向一个首选项窗口创build的。 然后在可见的用户控件上添加小号蓝色框。 它还提取文本和控件types信息（button，checkbox等）以及其他元信息。 这些图像也可以点击，以允许从屏幕截图下钻。
这个function真的把我吹走了。 它可能不是最好的，但是这个function非常棒。
我们一直比较喜欢LaTeX，因为我们的文档有很多沉重的math…但是，更重要的是，它是纯文本 ，这意味着使用我们的VCS（CVS，SVN，Git等）可以很容易地进行pipe理，在代码中生活 – 因此，在开发时没有更新文档的借口。
作为Kristopher的点头，我们是一个相当研究的组织（虽然不是.edu）…
我使用Visio来生成UML文档和时间表。 对于我来说，这些都是在devise时完成的，当我试图弄清楚我是如何组织的，或者应该如何工作。 然后，（希望）它们在实现完成后被更新，以便它们匹配实际完成的实现（实现从不匹配devise！）。
对于代码文档，我使用一些工具，取决于语言。 所有这些使用javadoc风格的评论，我喜欢的变化。
- Java – javadoc
- C / C ++ – doxygen
- ActionScript 2 – as2api
Visual Studio为C＃（也可能是其他.Net语言）提供了一个使用类似XML的注释的内置文档工具。 我相信其他人也提到过。
对于我们其余的文档（networking协议等），我们使用公司Wiki。 我们使用的是Confluence，尽pipe这里有很多Wiki的select。 我们发现使用维基非常有用，因为任何人都可以在需要时更新文档，而且也很容易访问（不会传递Word文件）。
不幸的是，我通常使用记事本卡住了。
使用C＃和.Net，我们使用Sandcastle将XML代码注释编译到帮助文件中。
对于用户和系统文档，我们有一个Wiki – 特别是Confluence 。
对于为最终用户编写文档，在开始查看特定工具之前，需要考虑很多事项。 这些包括：
- 你的工具要求是什么？ 这可以包括“作为HTML在networking浏览器中可用的内容”或者“作为CHM可离线浏览的内容”，或者两者兼而有之。
- 你需要的工具是否足够简单，以至于你的团队中的任何人都可以使用它，或者你是否有一个专门的技术作家，将他的整个一天花在应用程序？ 第一个需要一个简单的应用程序，为您做了很多工作。 第二个需要function强大，灵活的应用程序。
- 什么是你的内容的最佳performance？ HTML，维基，论坛，还是别的什么？
回答这些问题将帮助您比较您的工具选项。
Confluence和JavaDoc在这里。 汇总非项目特定的东西，如架构，操作方法，技巧，代码示例，一些错误报告等。
如果它是项目特定的并且不适合于JavaDoc，那么我只是简单地将纯文本* .txt文件作为支持文档添加到项目中。 到目前为止，它工作得很好。
这是另一个伟大的文档工具，完全免费供个人使用。
以下是我们使用的：
- 单词 – 用于创build大多数文档
- Visio – 用于创build图表以及线框
我们使用Fogbugz维基通用文档和SandCastle API。
我们也使用Sandcastle和GhostDoc ，但是对于Windows平台上的UML东西，我没有发现“免费”的价格比StarUML更好。
StarUML是一个巨大的价值。 发展似乎在过去三年停滞不前，但它是一个非常稳定的工具。 我已经使用了其他免费软件（如ArgoUML ），但是它们并没有被certificate是快速的或function完备的。 它不是一个好的商业工具的替代品，但是在我工作的大部分地方，没有人愿意为Enterprise Architect这样的东西掏钱。
对于用户文档和大多数其他forms的文档，我最常使用MS Word。
对于开发文档，特别是API文档，Javadoc和Doxygen等工具使用很多。 Wiki也很好。
除了学术界和研究界之外，我没有看到TeX或LaTeX的使用。
从devise到最终用户文档，以及详细介绍我们的实验室设置和谁在使用什么机器的文档，我们都进入了wiki（媒体维基）。 最终用户的东西被导入到acrobat中，并生成用户好的PDF（我认为真正的纸质文档仍然）。 我们使用Borland Together进行UMLbuild模（和代码生成，但这是另一篇文章）。 我们把testing人员指向维基，当他们去testing一个新的function，然后他们也得到写文档和产品的错误。 当我们开始这样做的时候（我们曾经有过作家，我们会一起工作），但是我已经变成了一个很大的粉丝。 我们的用户似乎也喜欢它。
有几个人已经提到了C＃xml文档，还有人提到了C / C ++ / Java的doxygen，但是我想提醒大家，它也支持C＃样式的文档。 它可以生成html，postscript，pdf和手册页的文档，所以你不需要卡住Sandcastle的帮助文件。
Word和Visio显然是事实上的标准工具。 但是为了使它们对于技术文档真正有用，你应该有非常好的模板设置，使格式化变得简单。 你不得不考虑的更多，你可以考虑的内容。 我使用了一大堆预设样式的Word文档，如节标题，正文格式，列表，代码块等。
在Visio中，我使用一组标准的形状来创build每种types的图（高级系统图，用户界面，工作stream等）
我其实对我的Word模板感到非常自豪。 这很干净。 我会通过电子邮件发送给任何想要副本的人。
如果你更喜欢乳胶的特殊编辑器，我会build议texmaker（用于linux），或者你可以用emacs去;）
