Read this book: http://en.wikipedia.org/wiki/The_Pragmatic_Programmer . There is some idee fixe inside, so that documentation should be built automatically. Think about using your IDE for this, or look for some additional tools. Most modern languages support generating documentation as you write the code. This can simply maintain your doc in touch with latest changes in the code.
I prefer to use a RTF editor which is a lot less clunkier than words. This way the formatting and all the headers/footers nonsense will not take up half your time. Wordpad has worked for me on several occasions. I'm stuck with Word for now though :(
embedded documentation, e.g. javadoc: good for describing APIs, not so good for the "big picture"
plain html: can be checked in under version control, a definite plus
a wiki, e.g. confluence -- great for collaboration, but has version control different from your source
LaTeX or somesuch: better suited for books or papers than typical documentation; support for graphics is cumbersome
an Office clone, e.g. OpenOffice: mostly the same as Word+Visio, but open source, with a nicer document format
I usually document the software structure (the "metaphors" of a project, component interrelations, external systems) up front, using Visio, in "freeform" UML. These are then embedded in confluence, which can be converted to PDF if someone wants a printout.
LyX is a WYSIWYM front end to LaTeX: You get the convenience of a document processor (somewhat similar to Word) with the consistency and power of LaTeX: It doesn't get in your way and can do a lot of things that professional writers need.
Note: The correct answer for you really depends on your way of thinking --- we can't decide this for you. This answer simply shows an excellent choice if you think of documentations as documents and want something similar to Word (where Word is good) that doesn't suck as Word (where Word is bad for programmers).
But many programmers think of documentation differently and hence prefer different metaphors. I myself had the same problem years ago, worked with LaTeX (as I am a mathematician), found LyX and finally settled on a Wiki/Source system that I wrote myself.
嗯，我从一开始就没有发现 MS-Word 有什么问题。 （即，如果您花时间了解如何有效地使用它）。 OpenOffice 确实是一个令人惊叹的软件。 可靠的免费替代方案 - 但如果您讨厌 MS Word 的布局相关问题，那么 OpenOffice 也会出现同样的问题。
我自己从未尝试过 Latex 系统，但听说它对科学工作有好处。 我认为，如果您只想专注于内容，那么使用 HTML 所见即所得编辑器最适合您。
Well I've never found anything wrong with MS-Word in the first place. (i.e if you take the time to know how to use it effectively). OpenOffice indeed is an amazing & credible free alternative - but then if you hate MS Word for layout related problems, the same problem is gonna occur with OpenOffice too.
Never tried the Latex system myself, but have heard its good for scientific work. I think using some HTML WYSIWYG editor would be best for you, if you want to just focus on the content.
我考虑过使用 wiki，但我决定使用修改后的 Markdown 表示法，原因很简单，wiki 的内容不容易导出并分发到 wiki 本身之外，而 Markdown 可以呈现为 HTML。
回答 chris 关于我的工作流程的问题：我使用类似记事本的应用程序编写文档 (TextWrangler，只是因为它的自动换行功能）以其原始 Markdown 格式。 然后我有一个 小型本地主机文档网站 ，其中 我修改后的 Markdown 解析器（扩展了一些功能和更多面向 HTML 的功能），用于检查时间戳文档文件 - 如果文件已更新，它会将该文件解析为 HTML，并将该文件存储在缓存中。
这样我就可以在桌面上编辑源文档，只需在浏览器中按 F5 即可立即查看结果。
I considered a wiki, but I decided to go with a modified Markdown notation, for the simple reason, that a wiki's content isn't easily exported and distributed outside of the wiki itself, while the Markdown can be rendered into HTML.
Answer to chris' question about my workflow: I write the documentation with a Notepad-like application (TextWrangler, only because of its word-wrapping feature) in its raw Markdown format. Then I have a small localhost documentation website with my modified Markdown parser (extended for a few features and a bit more HTML-oriented functionality) that checks for the timestamps for the documentation files - if a file has been updated, it parses that file into HTML, and stores the file in a cache.
This way I'm able to edit the source documentation on my desktop, and just press F5 in my browser to see the results immediately.
Vim 是任何需要以最有效的方式编写纯文本的解决方案。 如果您需要格式化，请使用 XML、Latex 或类似的东西（在 Vim 中）。
Vim 改变了我的生活！
Vim is the solution for anything that means writing plain text in the most efficient possible way. If you need formatting, then use XML, Latex or something similar (in Vim).
At phc, we started with latex, then moved to docbook, and have settled (permanently I hope) on Restructured Text/Sphinx.
Latex was chosen because we are academics, and latex is the tool of choice. I believe it didn't generate good enough HTML.
Docbook was chosen for power, but it was very unwieldy. It put us off writing any documentation: code had to be manually formatted, we kept forgetting the syntax, and it was difficult to read. The learning curve was also steep.
Finally, we moved to reST, using sphinx, and that was a great decision. Documentation is now very easy to write, and both PDF and HTML versions look beautiful (though the PDF could do with some customization). Its very easy to customize too.
The best bit about reST though, is that its human readable in source form. That is a wonderful advantage. I've switched to using reST for all my stuff now, especially anything over the web (except of course academic papers, where one would be foolish to use anything but latex).
You may want to look into doxygen at http://www.doxygen.nl/, see their nice examples. In this case, the documentation is presented by tags in comments in the source.
Another option would be to use an online system like trac from http://trac.edgewall.org/ which is a wiki/doc/issuetracking system that lives on top of subversion.
一旦您定义了所有样式并用正确的样式标记了所有文档内容而不是以临时方式格式化，您会惊讶地发现快速生成美观的 Word 文档是多么容易每次。
这里更广泛的问题是，每个人都会在 Word 上花费大量时间，但很少有公司投资于 Word 培训。 在某些时候，您必须硬着头皮花时间教自己如何正确使用它，就像使用任何其他工具一样。
My solution to this was to invest some time in creating a decent Word Template for myself.
The important thing to do is make sure you have a Style defined for everything you can put in the document.
Once you have all the Styles defined and all of the document content tagged with the correct Style instead of formatted in an ad hoc fashion, you'll be surprised how easy it is to produce good looking Word documents quickly every time.
The wider problem here is that everyone spends hours in Word and yet it is very rare for companies to invest in Word training. At some point you have to bite the bullet and take the time to teach yourself how to use it properly, just like you would with any other tool.
在我看来，LyX 在某些情况下非常出色，在其他情况下也很方便，但有时会妨碍您。 我认为它应该被视为 LaTeX 生产力的助推器。 换句话说，在尝试 LyX 之前先学习使用 LaTeX。 当然，两者都是免费的，并且可用于 Windows，但与 MS Word 相比，学习曲线相当陡峭。 对于长文档或大量类似文档，LaTeX/LyX 可能是一项值得的投资。
Anything you can do with LyX you can do with LaTeX. LaTeX is suitable for all sorts of things; it has been used for everything from manuals to lecture slides to novels.
I think LaTeX is probably worth looking into as an option; if you've ever wanted to "code" for your word processor, LaTeX is for you. At the simplest level you can define new commands to do things for you, but there's a lot of power there. And the output looks really neat.
In my opinion, LyX is fantastic in certain circumstances, handy in others, and occasionally just gets in your way. I think it should be seen as a productivity booster for LaTeX. In other words, learn to use LaTeX before trying LyX. Both are of course free and available for Windows, though the learning curve is quite steep compared with MS Word. For long documents, or plenty of similar documents, LaTeX/LyX is probably a worthwhile investment.
对于我个人也发现的 MS Word 令人沮丧的体验，我的回应是完全避免它并使用自动文档工具，例如 GhostDoc 从我已经在代码中编写的内容生成 XML（DRY！）并处理来自基于 XSLT 的 XML Intranet 网站或类似的网站。
Despite all efforts and reasonable expectation I don't think Word Processing has been "solved" yet.
My response to what I also personally find a deeply frustrating experience with MS Word is to avoid it altogether and use an auto-documenting tool like GhostDoc to generate XML from what I've already written in the code (DRY!) and deal with the XML from an XSLT based intranet site or similar later.
LaTeX is an extremely powerful tool and might well be overkill here as it is designed for scientific/mathematical literature. It has a (relatively) steep learning curve and can be tricky to coax to do exactly as you want if you're new to it. I LOVE LaTeX, but it is not really a general purpose word processor.
LaTeX is really a very powerful language if you need to write documents.
Perhaps you can try texmaker, a cross-platform LaTeX editor:
Texmaker is a clean, highly
configurable LaTeX editor with good
hot key support and extensive Latex
documentation. Texmaker integrates
many tools needed to develop
documents with LaTeX, in just one
application. It has some nice
features such as syntax highlighting,
insertion of 370 mathematical symbols
with only one click, and "structure
view" of the document for easier
navigation.
您可以使用自己的 XML 格式编写文档，然后使用 XSL 将其转换为任何格式（例如通过 FOP+XSL-FO 的 PDF）。
另请参阅 DocBook XML 格式。
You could write your documentation using your own XML format and then transform it into any format with XSL (e.g. PDF via FOP+XSL-FO ).
See also the DocBook XML format.
I've found that wikis can be good for this. Find a wiki you like that lets you do a bit of formatting, but nothing really heavy. Ideally it should let you format code easily too - to be honest, the markdown available on SO is probably a good start.
That way:
You have change tracking built-in (assuming a decent wiki)
You can edit from anywhere
Everyone always sees the same documentation (instant distribution)
You can concentrate on content instead of formatting
Are you talking about documenting your actual code? If so, I recommend Doxygen for unmanaged code and Sandcastle for managed code. Both will compile your help or build it as a website for you.
Both applications will read special tags above functions / classes / variables and compile that into the help.
发布评论
评论（21）
阅读这本书：http://en.wikipedia.org/wiki/The_Pragmatic_Programmer。 里面有一些 idee 修复程序，因此应该自动构建文档。 考虑使用您的 IDE 来实现此目的，或者寻找一些其他工具。 大多数现代语言都支持在编写代码时生成文档。 这可以简单地使您的文档与代码中的最新更改保持联系。
Read this book: http://en.wikipedia.org/wiki/The_Pragmatic_Programmer . There is some idee fixe inside, so that documentation should be built automatically. Think about using your IDE for this, or look for some additional tools. Most modern languages support generating documentation as you write the code. This can simply maintain your doc in touch with latest changes in the code.
我更喜欢使用 RTF 编辑器，它比文字简单得多。 这样，格式设置和所有页眉/页脚的废话就不会占用您一半的时间。 写字板曾多次为我工作。 不过我现在还是用Word:(
I prefer to use a RTF editor which is a lot less clunkier than words. This way the formatting and all the headers/footers nonsense will not take up half your time. Wordpad has worked for me on several occasions. I'm stuck with Word for now though :(
有很多可能的方法：
我通常记录软件结构（项目的“隐喻”、组件相互关系、外部系统）预先使用 Visio，以“自由格式”UML 形式。 然后将它们嵌入到 confluence 中，如果有人想要打印输出，可以将其转换为 PDF。
there are a lot of possible ways:
I usually document the software structure (the "metaphors" of a project, component interrelations, external systems) up front, using Visio, in "freeform" UML. These are then embedded in confluence, which can be converted to PDF if someone wants a printout.
LyX
LyX 是一个 WYSIWYM LaTeX 前端：您可以获得文档处理器的便利（有点类似于 Word）以及 LaTeX 的一致性和强大功能：它不妨碍你，并且可以做很多专业作家需要的事情。
注意：您的正确答案实际上取决于您的思维方式 --- 我们无法为您做出决定。 如果您将文档视为文档，并且想要类似于 Word（Word 很好）但又不像 Word（Word 对程序员不利）的东西，那么这个答案只是显示了一个绝佳的选择。
但许多程序员对文档的看法不同，因此更喜欢不同的隐喻。 我自己几年前也遇到过同样的问题，使用 LaTeX（因为我是一名数学家），找到了 LyX，并最终选择了我自己编写的 Wiki/Source 系统。
LyX
LyX is a WYSIWYM front end to LaTeX: You get the convenience of a document processor (somewhat similar to Word) with the consistency and power of LaTeX: It doesn't get in your way and can do a lot of things that professional writers need.
Note: The correct answer for you really depends on your way of thinking --- we can't decide this for you. This answer simply shows an excellent choice if you think of documentations as documents and want something similar to Word (where Word is good) that doesn't suck as Word (where Word is bad for programmers).
But many programmers think of documentation differently and hence prefer different metaphors. I myself had the same problem years ago, worked with LaTeX (as I am a mathematician), found LyX and finally settled on a Wiki/Source system that I wrote myself.
嗯，我从一开始就没有发现 MS-Word 有什么问题。 （即，如果您花时间了解如何有效地使用它）。 OpenOffice 确实是一个令人惊叹的软件。 可靠的免费替代方案 - 但如果您讨厌 MS Word 的布局相关问题，那么 OpenOffice 也会出现同样的问题。
我自己从未尝试过 Latex 系统，但听说它对科学工作有好处。 我认为，如果您只想专注于内容，那么使用 HTML 所见即所得编辑器最适合您。
Well I've never found anything wrong with MS-Word in the first place. (i.e if you take the time to know how to use it effectively). OpenOffice indeed is an amazing & credible free alternative - but then if you hate MS Word for layout related problems, the same problem is gonna occur with OpenOffice too.
Never tried the Latex system myself, but have heard its good for scientific work. I think using some HTML WYSIWYG editor would be best for you, if you want to just focus on the content.
我考虑过使用 wiki，但我决定使用修改后的 Markdown 表示法，原因很简单，wiki 的内容不容易导出并分发到 wiki 本身之外，而 Markdown 可以呈现为 HTML。
回答 chris 关于我的工作流程的问题：我使用类似记事本的应用程序编写文档 (TextWrangler，只是因为它的自动换行功能）以其原始 Markdown 格式。 然后我有一个 小型本地主机文档网站 ，其中 我修改后的 Markdown 解析器（扩展了一些功能和更多面向 HTML 的功能），用于检查时间戳文档文件 - 如果文件已更新，它会将该文件解析为 HTML，并将该文件存储在缓存中。
这样我就可以在桌面上编辑源文档，只需在浏览器中按 F5 即可立即查看结果。
I considered a wiki, but I decided to go with a modified Markdown notation, for the simple reason, that a wiki's content isn't easily exported and distributed outside of the wiki itself, while the Markdown can be rendered into HTML.
Answer to chris' question about my workflow: I write the documentation with a Notepad-like application (TextWrangler, only because of its word-wrapping feature) in its raw Markdown format. Then I have a small localhost documentation website with my modified Markdown parser (extended for a few features and a bit more HTML-oriented functionality) that checks for the timestamps for the documentation files - if a file has been updated, it parses that file into HTML, and stores the file in a cache.
This way I'm able to edit the source documentation on my desktop, and just press F5 in my browser to see the results immediately.
我还没有时间尝试，但我一直认为 AsciiDoc 会对这种事情有好处。
I haven't got around to trying it yet, but I've always thought AsciiDoc would be good for this kind of thing.
如果你想要比 LaTeX 更简单的东西，你可以看看 ReStructured Text
If you want something simpler than LaTeX, you can have a look at ReStructured Text
Vim 是任何需要以最有效的方式编写纯文本的解决方案。 如果您需要格式化，请使用 XML、Latex 或类似的东西（在 Vim 中）。
Vim 改变了我的生活！
Vim is the solution for anything that means writing plain text in the most efficient possible way. If you need formatting, then use XML, Latex or something similar (in Vim).
Vim changed my life!
简单的答案：LaTeX 听起来正是您正在寻找的。
我自己用它来编写文档。 如果可以的话，我永远不会再回到Word。
Simple answer: LaTeX sounds like just what you are looking for.
I use it for writing documentation myself. I will never go back to Word if I have the option.
在 phc，我们从 Latex 开始，然后转向 docbook，并最终决定（我希望永远）Restructed Text/Sphinx 。
选择 Latex 是因为我们是学者，而 Latex 是首选工具。 我相信它没有生成足够好的 HTML。
选择 Docbook 是因为其功能强大，但它非常笨重。 它让我们无法编写任何文档：代码必须手动格式化，我们总是忘记语法，而且很难阅读。 学习曲线也很陡峭。
最后，我们转向 reST，使用 sphinx，这是一个很棒的决定。 现在编写文档非常容易，PDF 和HTML 版本 看起来很漂亮（尽管 PDF 可以进行一些自定义）。 它也很容易定制。
不过，关于 reST 的最好的一点是它的源代码形式是人类可读的。 这是一个很好的优势。 我现在已经转而使用 reST 来处理我的所有东西，尤其是网络上的任何东西（当然学术论文除外，在学术论文中，使用除乳胶以外的任何东西都是愚蠢的）。
At phc, we started with latex, then moved to docbook, and have settled (permanently I hope) on Restructured Text/Sphinx.
Latex was chosen because we are academics, and latex is the tool of choice. I believe it didn't generate good enough HTML.
Docbook was chosen for power, but it was very unwieldy. It put us off writing any documentation: code had to be manually formatted, we kept forgetting the syntax, and it was difficult to read. The learning curve was also steep.
Finally, we moved to reST, using sphinx, and that was a great decision. Documentation is now very easy to write, and both PDF and HTML versions look beautiful (though the PDF could do with some customization). Its very easy to customize too.
The best bit about reST though, is that its human readable in source form. That is a wonderful advantage. I've switched to using reST for all my stuff now, especially anything over the web (except of course academic papers, where one would be foolish to use anything but latex).
您可能想在 http://www.doxygen.nl/ 上了解 doxygen，查看他们很好的示例。 在这种情况下，文档通过源代码中注释中的标签来呈现。
另一种选择是使用在线系统，例如 http://trac.edgewall.org/ 中的 trac是一个基于 subversion 的 wiki/doc/issuetracking 系统。
You may want to look into doxygen at http://www.doxygen.nl/, see their nice examples. In this case, the documentation is presented by tags in comments in the source.
Another option would be to use an online system like trac from http://trac.edgewall.org/ which is a wiki/doc/issuetracking system that lives on top of subversion.
我的解决方案是花一些时间为自己创建一个像样的 Word 模板。
要做的重要事情是确保您为可以放入文档中的所有内容定义了样式。
一旦您定义了所有样式并用正确的样式标记了所有文档内容而不是以临时方式格式化，您会惊讶地发现快速生成美观的 Word 文档是多么容易每次。
这里更广泛的问题是，每个人都会在 Word 上花费大量时间，但很少有公司投资于 Word 培训。 在某些时候，您必须硬着头皮花时间教自己如何正确使用它，就像使用任何其他工具一样。
My solution to this was to invest some time in creating a decent Word Template for myself.
The important thing to do is make sure you have a Style defined for everything you can put in the document.
Once you have all the Styles defined and all of the document content tagged with the correct Style instead of formatted in an ad hoc fashion, you'll be surprised how easy it is to produce good looking Word documents quickly every time.
The wider problem here is that everyone spends hours in Word and yet it is very rare for companies to invest in Word training. At some point you have to bite the bullet and take the time to teach yourself how to use it properly, just like you would with any other tool.
用 LyX 能做的任何事，用 LaTeX 也能做。 LaTeX 适用于各种事物； 它已被用于从手册到讲座幻灯片到小说的各种内容。
我认为 LaTeX 可能值得考虑作为一种选择； 如果您曾经想为文字处理器“编码”，那么 LaTeX 适合您。 在最简单的层面上，您可以定义新的命令来为您做事，但其中有很多功能。 输出看起来真的很整洁。
在我看来，LyX 在某些情况下非常出色，在其他情况下也很方便，但有时会妨碍您。 我认为它应该被视为 LaTeX 生产力的助推器。 换句话说，在尝试 LyX 之前先学习使用 LaTeX。 当然，两者都是免费的，并且可用于 Windows，但与 MS Word 相比，学习曲线相当陡峭。 对于长文档或大量类似文档，LaTeX/LyX 可能是一项值得的投资。
Anything you can do with LyX you can do with LaTeX. LaTeX is suitable for all sorts of things; it has been used for everything from manuals to lecture slides to novels.
I think LaTeX is probably worth looking into as an option; if you've ever wanted to "code" for your word processor, LaTeX is for you. At the simplest level you can define new commands to do things for you, but there's a lot of power there. And the output looks really neat.
In my opinion, LyX is fantastic in certain circumstances, handy in others, and occasionally just gets in your way. I think it should be seen as a productivity booster for LaTeX. In other words, learn to use LaTeX before trying LyX. Both are of course free and available for Windows, though the learning curve is quite steep compared with MS Word. For long documents, or plenty of similar documents, LaTeX/LyX is probably a worthwhile investment.
使用 HTML 怎么样？ 这样，如果许多人需要从许多地方访问该文档，您就可以发布该文档。
What about using HTML? This way you could then publish the documentation if there will be need for many people to access it from many places.
尽管付出了所有的努力和合理的期望，我认为文字处理还没有被“解决”。
对于我个人也发现的 MS Word 令人沮丧的体验，我的回应是完全避免它并使用自动文档工具，例如 GhostDoc 从我已经在代码中编写的内容生成 XML（DRY！）并处理来自基于 XSLT 的 XML Intranet 网站或类似的网站。
Despite all efforts and reasonable expectation I don't think Word Processing has been "solved" yet.
My response to what I also personally find a deeply frustrating experience with MS Word is to avoid it altogether and use an auto-documenting tool like GhostDoc to generate XML from what I've already written in the code (DRY!) and deal with the XML from an XSLT based intranet site or similar later.
LaTeX 是一个极其强大的工具，但在这里可能有些过头了，因为它是为科学/数学文献而设计的。 它有一个（相对）陡峭的学习曲线，如果你是新手，要哄它完全按照你想要的方式做可能会很棘手。 我喜欢 LaTeX，但它并不是真正的通用文字处理器。
您是否考虑过 OpenOffice？
LaTeX is an extremely powerful tool and might well be overkill here as it is designed for scientific/mathematical literature. It has a (relatively) steep learning curve and can be tricky to coax to do exactly as you want if you're new to it. I LOVE LaTeX, but it is not really a general purpose word processor.
Have you considered OpenOffice instead?
如果您需要编写文档，LaTeX确实是一种非常强大的语言。
也许你可以尝试 texmaker，一个跨平台的 LaTeX 编辑器：
LaTeX is really a very powerful language if you need to write documents.
Perhaps you can try texmaker, a cross-platform LaTeX editor:
您可以使用自己的 XML 格式编写文档，然后使用 XSL 将其转换为任何格式（例如通过 FOP+XSL-FO 的 PDF）。
另请参阅 DocBook XML 格式。
You could write your documentation using your own XML format and then transform it into any format with XSL (e.g. PDF via FOP+XSL-FO ).
See also the DocBook XML format.
我发现维基百科对此很有帮助。 找到一个您喜欢的 wiki，它可以让您进行一些格式化操作，但不要做任何繁重的工作。 理想情况下，它也应该让您轻松格式化代码 - 说实话，SO 上可用的降价可能是一个好的开始。
这样：
I've found that wikis can be good for this. Find a wiki you like that lets you do a bit of formatting, but nothing really heavy. Ideally it should let you format code easily too - to be honest, the markdown available on SO is probably a good start.
That way:
您是在谈论记录您的实际代码吗？ 如果是这样，我推荐 Doxygen 用于非托管代码，并 Sandcastle 用于托管代码。 两者都会编译您的帮助或将其构建为您的网站。
这两个应用程序都会读取函数/类/变量上面的特殊标签，并将其编译到帮助中。
Are you talking about documenting your actual code? If so, I recommend Doxygen for unmanaged code and Sandcastle for managed code. Both will compile your help or build it as a website for you.
Both applications will read special tags above functions / classes / variables and compile that into the help.