As a developer I really don't like writing documentation but when I have to I'd like to make the process as painless as possible.
作为一名开发人员,我真的不喜欢编写文档,但是当我不得不尽可能地让这个过程变得无痛时。
The problem with Word is that it constantly gets in my way. I worry more about the layout than about the actual content ... that's why I'd like to get rid of Word.
Word的问题在于它经常妨碍我。我更担心布局而不是实际内容......这就是我想摆脱Word的原因。
Ideally I'd like to write my content and then 'compile' it into a document.
理想情况下,我想编写我的内容,然后将其“编译”成文档。
I've heard of LaTeX but I don't have any experience with it whatsoever. Would this be the right technology for the job? What editor (Windows) should I use? Is it a good idea to start with LyX?
我听说过LaTeX,但我对它没有任何经验。这是适合这项工作的技术吗?我应该使用什么编辑器(Windows)?从LyX开始是一个好主意吗?
EDIT: I'm not asking about documenting code (I use Sandcastle for that).
编辑:我不是要求记录代码(我使用Sandcastle)。
Update 2014:
We have now switched to GFM (GitHub Flavored Markdown).
我们现在已切换到GFM(GitHub Flavored Markdown)。
- It's really easy to work with.
- Write code & documentation in the same IDE!
- Everything can be versioned!
- Get great output either as raw txt, html or pdf!
这很容易使用。
在同一个IDE中编写代码和文档!
一切都可以版本化!
以raw txt,html或pdf的形式获得出色的输出!
21 个解决方案
#1
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.
我发现维基可能对此有好处。找一个你喜欢的wiki,让你做一些格式化,但没有什么真正重。理想情况下,它应该让您轻松地格式化代码 - 说实话,SO上的降价可能是一个良好的开端。
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
你有内置的更改跟踪(假设一个体面的维基)
您可以在任何地方进行编辑
每个人都看到相同的文档(即时分发)
您可以专注于内容而不是格式化
#2
My solution to this was to invest some time in creating a decent Word Template for myself.
我的解决方案是花一些时间为自己创建一个体面的Word模板。
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.
一旦您定义了所有样式并且所有文档内容都使用正确的样式标记而不是以临时方式格式化,您会惊讶地发现每次快速生成好看的Word文档是多么容易。
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.
这里更广泛的问题是每个人都花费数小时在Word中,但公司很少投资Word培训。在某些时候,你必须咬紧牙关,花时间教自己如何正确使用它,就像你使用任何其他工具一样。
#3
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.
你可以用LyX做任何事情,你可以用LaTeX。 LaTeX适用于各种事物;它已被用于从手册到演讲幻灯片到小说的所有内容。
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.
我认为LaTeX可能值得考虑作为一种选择;如果你曾经想为你的文字处理器“编码”,那么LaTeX就适合你。在最简单的级别,您可以定义新的命令来为您做事,但那里有很多功能。输出看起来非常整洁。
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.
在我看来,LyX在某些情况下非常棒,在其他情况下很方便,偶尔会妨碍你。我认为它应该被视为LaTeX的生产力助推器。换句话说,在尝试LyX之前学习使用LaTeX。两者当然都是免费的,适用于Windows,但与MS Word相比,学习曲线相当陡峭。对于长文档或大量类似文档,LaTeX / LyX可能是值得投资的。
#4
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.
您可以使用自己的XML格式编写文档,然后使用XSL将其转换为任何格式(例如,通过FOP + XSL-FO的PDF)。另请参阅DocBook XML格式。
#5
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是一个非常强大的工具,因为它是专为科学/数学文献而设计的。它有一个(相对)陡峭的学习曲线,如果你是新手,可能很难哄骗你完全按照自己的意愿去做。我喜欢LaTeX,但它并不是一个通用的文字处理器。
Have you considered OpenOffice instead?
您是否考虑过OpenOffice?
#6
LaTeX is really a very powerful language if you need to write documents.
如果您需要编写文档,LaTeX实际上是一种非常强大的语言。
Perhaps you can try texmaker, a cross-platform LaTeX editor:
也许你可以尝试texmaker,一个跨平台的LaTeX编辑器:
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.
Texmaker是一个干净,高度可配置的LaTeX编辑器,具有良好的热键支持和广泛的Latex文档。 Texmaker在一个应用程序中集成了使用LaTeX开发文档所需的许多工具。它具有一些很好的功能,例如语法高亮,只需单击一下即可插入370个数学符号,以及文档的“结构视图”,以便于导航。
#7
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.
使用HTML怎么样?这样,如果需要许多人从许多地方访问它,您就可以发布文档。
#8
Despite all efforts and reasonable expectation I don't think Word Processing has been "solved" yet.
尽管所有的努力和合理的期望,我不认为Word Processing已经“解决”了。
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.
我对个人发现MS Word令人深感沮丧的经历的回应是完全避免它,并使用像GhostDoc这样的自动文档工具从我已经在代码中编写的内容生成XML(DRY!)并处理来自基于XSLT的Intranet站点或类似的XML。
#9
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.
你在谈论记录你的实际代码吗?如果是这样,我推荐Doxygen用于非托管代码,Sandcastle用于托管代码。两者都会编译您的帮助或为您构建一个网站。
Both applications will read special tags above functions / classes / variables and compile that into the help.
两个应用程序都将读取函数/类/变量上方的特殊标记,并将其编译到帮助中。
#10
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.
好吧,我从来没有发现MS-Word有任何问题。 (即如果你花时间知道如何有效地使用它)。 OpenOffice确实是一个令人惊讶且可靠的免费替代方案 - 但是如果你讨厌MS Word来解决与布局相关的问题,那么OpenOffice也会出现同样的问题。
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.
从未尝试过乳胶系统,但听说它对科学工作有益。我认为如果你只想专注于内容,使用一些HTML WYSIWYG编辑器最适合你。
#11
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.
我考虑过一个wiki,但我决定采用改进的Markdown表示法,原因很简单,wiki的内容不容易导出并分发到wiki本身之外,而Markdown可以呈现为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.
回答克里斯关于我的工作流程的问题:我使用类似记事本的应用程序(TextWrangler,仅因为它的自动换行功能)以原始Markdown格式编写文档。然后我有一个小的localhost文档网站,其中包含我修改过的Markdown解析器(扩展了一些功能和更多面向HTML的功能),用于检查文档文件的时间戳 - 如果文件已更新,它会将该文件解析为HTML,并将文件存储在缓存中。
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.
通过这种方式,我可以在桌面上编辑源文档,只需在浏览器中按F5即可立即查看结果。
#12
I haven't got around to trying it yet, but I've always thought AsciiDoc would be good for this kind of thing.
我还没有尝试过,但我一直认为AsciiDoc会对这种事情有好处。
#13
If you want something simpler than LaTeX, you can have a look at ReStructured Text
如果您想要比LaTeX更简单的东西,您可以查看ReStructured Text
#14
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.
阅读本书:http://en.wikipedia.org/wiki/The_Pragmatic_Programmer。内部有一些idee fixe,因此应该自动构建文档。考虑使用您的IDE,或寻找一些额外的工具。大多数现代语言都支持在编写代码时生成文档。这可以简单地使您的文档与代码中的最新更改保持联系。
#15
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 :(
我更喜欢使用RTF编辑器,它比文字更笨拙。这样格式化和所有页眉/页脚废话不会花费你一半的时间。 Wordpad曾多次为我工作过。我现在仍然坚持使用Word :(
#16
there are a lot of possible ways:
有很多可能的方法:
- 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
嵌入式文档,例如javadoc:很适合描述API,对“大图片”不太好
plain html:可以在版本控制下检查,一定加分
维基,例如汇合 - 非常适合协作,但版本控制与您的源不同
LaTeX或其他:比典型的文档更适合书籍或论文;对图形的支持很麻烦
Office克隆,例如OpenOffice:与Word + Visio大致相同,但是开源,具有更好的文档格式
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.
我通常使用Visio在“*形式”UML中预先记录软件结构(项目的“隐喻”,组件相互关系,外部系统)。然后将它们嵌入汇合中,如果有人想要打印输出,可以将其转换为PDF。
#17
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.
LyX是LaTeX的WYSIWYM前端:你可以获得文档处理器(有点类似于Word)的便利性和LaTeX的一致性和强大功能:它不会妨碍你,可以做很多专业作家需要的东西。
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).
注意:正确答案取决于您的思维方式 - 我们无法为您做出决定。如果您将文档视为文档并希望将类似于Word(Word很好)的内容与Word不相似(Word对程序员不利),那么这个答案只是显示了一个很好的选择。
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.
但是许多程序员对文档的看法不同,因此更喜欢不同的隐喻。我自己在几年前遇到了同样的问题,与LaTeX合作(因为我是一名数学家),找到了LyX并最终选择了我自己编写的Wiki / Source系统。
#18
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是任何意味着以最有效的方式编写纯文本的解决方案。如果你需要格式化,那么使用XML,Latex或类似的东西(在Vim中)。
Vim changed my life!
Vim改变了我的生活!
#19
Simple answer: LaTeX sounds like just what you are looking for.
简单的回答:LaTeX听起来就像你正在寻找的。
I use it for writing documentation myself. I will never go back to Word if I have the option.
我自己用它来写文档。如果我有选择权,我将永远不会回到Word。
#20
At phc, we started with latex, then moved to docbook, and have settled (permanently I hope) on Restructured Text/Sphinx.
在phc,我们从乳胶开始,然后转到docbook,并在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.
选择乳胶是因为我们是学者,乳胶是首选工具。我相信它没有产生足够好的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.
Docbook被选为权力,但它非常笨拙。它让我们不写任何文档:代码必须手动格式化,我们一直忘记语法,而且很难阅读。学习曲线也很陡峭。
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.
最后,我们使用sphinx转移到reST,这是一个很好的决定。文档现在非常容易编写,PDF和HTML版本看起来都很漂亮(尽管PDF可以进行一些自定义)。它也很容易定制。
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).
关于reST的最好的一点是,它的源代码形式是人类可读的。这是一个很好的优势。我现在转而使用reST来处理我所有的东西,尤其是网络上的任何东西(当然除了学术论文,除了乳胶之外,使用任何东西都是愚蠢的)。
#21
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.
您可以在http://www.doxygen.nl/上查看doxygen,看看他们的好例子。在这种情况下,文档由源代码中的注释中的标记显示。
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.
另一种选择是使用来自http://trac.edgewall.org/的trac等在线系统,这是一个生活在颠覆之上的wiki / doc / issuetracking系统。
#1
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.
我发现维基可能对此有好处。找一个你喜欢的wiki,让你做一些格式化,但没有什么真正重。理想情况下,它应该让您轻松地格式化代码 - 说实话,SO上的降价可能是一个良好的开端。
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
你有内置的更改跟踪(假设一个体面的维基)
您可以在任何地方进行编辑
每个人都看到相同的文档(即时分发)
您可以专注于内容而不是格式化
#2
My solution to this was to invest some time in creating a decent Word Template for myself.
我的解决方案是花一些时间为自己创建一个体面的Word模板。
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.
一旦您定义了所有样式并且所有文档内容都使用正确的样式标记而不是以临时方式格式化,您会惊讶地发现每次快速生成好看的Word文档是多么容易。
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.
这里更广泛的问题是每个人都花费数小时在Word中,但公司很少投资Word培训。在某些时候,你必须咬紧牙关,花时间教自己如何正确使用它,就像你使用任何其他工具一样。
#3
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.
你可以用LyX做任何事情,你可以用LaTeX。 LaTeX适用于各种事物;它已被用于从手册到演讲幻灯片到小说的所有内容。
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.
我认为LaTeX可能值得考虑作为一种选择;如果你曾经想为你的文字处理器“编码”,那么LaTeX就适合你。在最简单的级别,您可以定义新的命令来为您做事,但那里有很多功能。输出看起来非常整洁。
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.
在我看来,LyX在某些情况下非常棒,在其他情况下很方便,偶尔会妨碍你。我认为它应该被视为LaTeX的生产力助推器。换句话说,在尝试LyX之前学习使用LaTeX。两者当然都是免费的,适用于Windows,但与MS Word相比,学习曲线相当陡峭。对于长文档或大量类似文档,LaTeX / LyX可能是值得投资的。
#4
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.
您可以使用自己的XML格式编写文档,然后使用XSL将其转换为任何格式(例如,通过FOP + XSL-FO的PDF)。另请参阅DocBook XML格式。
#5
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是一个非常强大的工具,因为它是专为科学/数学文献而设计的。它有一个(相对)陡峭的学习曲线,如果你是新手,可能很难哄骗你完全按照自己的意愿去做。我喜欢LaTeX,但它并不是一个通用的文字处理器。
Have you considered OpenOffice instead?
您是否考虑过OpenOffice?
#6
LaTeX is really a very powerful language if you need to write documents.
如果您需要编写文档,LaTeX实际上是一种非常强大的语言。
Perhaps you can try texmaker, a cross-platform LaTeX editor:
也许你可以尝试texmaker,一个跨平台的LaTeX编辑器:
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.
Texmaker是一个干净,高度可配置的LaTeX编辑器,具有良好的热键支持和广泛的Latex文档。 Texmaker在一个应用程序中集成了使用LaTeX开发文档所需的许多工具。它具有一些很好的功能,例如语法高亮,只需单击一下即可插入370个数学符号,以及文档的“结构视图”,以便于导航。
#7
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.
使用HTML怎么样?这样,如果需要许多人从许多地方访问它,您就可以发布文档。
#8
Despite all efforts and reasonable expectation I don't think Word Processing has been "solved" yet.
尽管所有的努力和合理的期望,我不认为Word Processing已经“解决”了。
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.
我对个人发现MS Word令人深感沮丧的经历的回应是完全避免它,并使用像GhostDoc这样的自动文档工具从我已经在代码中编写的内容生成XML(DRY!)并处理来自基于XSLT的Intranet站点或类似的XML。
#9
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.
你在谈论记录你的实际代码吗?如果是这样,我推荐Doxygen用于非托管代码,Sandcastle用于托管代码。两者都会编译您的帮助或为您构建一个网站。
Both applications will read special tags above functions / classes / variables and compile that into the help.
两个应用程序都将读取函数/类/变量上方的特殊标记,并将其编译到帮助中。
#10
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.
好吧,我从来没有发现MS-Word有任何问题。 (即如果你花时间知道如何有效地使用它)。 OpenOffice确实是一个令人惊讶且可靠的免费替代方案 - 但是如果你讨厌MS Word来解决与布局相关的问题,那么OpenOffice也会出现同样的问题。
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.
从未尝试过乳胶系统,但听说它对科学工作有益。我认为如果你只想专注于内容,使用一些HTML WYSIWYG编辑器最适合你。
#11
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.
我考虑过一个wiki,但我决定采用改进的Markdown表示法,原因很简单,wiki的内容不容易导出并分发到wiki本身之外,而Markdown可以呈现为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.
回答克里斯关于我的工作流程的问题:我使用类似记事本的应用程序(TextWrangler,仅因为它的自动换行功能)以原始Markdown格式编写文档。然后我有一个小的localhost文档网站,其中包含我修改过的Markdown解析器(扩展了一些功能和更多面向HTML的功能),用于检查文档文件的时间戳 - 如果文件已更新,它会将该文件解析为HTML,并将文件存储在缓存中。
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.
通过这种方式,我可以在桌面上编辑源文档,只需在浏览器中按F5即可立即查看结果。
#12
I haven't got around to trying it yet, but I've always thought AsciiDoc would be good for this kind of thing.
我还没有尝试过,但我一直认为AsciiDoc会对这种事情有好处。
#13
If you want something simpler than LaTeX, you can have a look at ReStructured Text
如果您想要比LaTeX更简单的东西,您可以查看ReStructured Text
#14
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.
阅读本书:http://en.wikipedia.org/wiki/The_Pragmatic_Programmer。内部有一些idee fixe,因此应该自动构建文档。考虑使用您的IDE,或寻找一些额外的工具。大多数现代语言都支持在编写代码时生成文档。这可以简单地使您的文档与代码中的最新更改保持联系。
#15
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 :(
我更喜欢使用RTF编辑器,它比文字更笨拙。这样格式化和所有页眉/页脚废话不会花费你一半的时间。 Wordpad曾多次为我工作过。我现在仍然坚持使用Word :(
#16
there are a lot of possible ways:
有很多可能的方法:
- 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
嵌入式文档,例如javadoc:很适合描述API,对“大图片”不太好
plain html:可以在版本控制下检查,一定加分
维基,例如汇合 - 非常适合协作,但版本控制与您的源不同
LaTeX或其他:比典型的文档更适合书籍或论文;对图形的支持很麻烦
Office克隆,例如OpenOffice:与Word + Visio大致相同,但是开源,具有更好的文档格式
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.
我通常使用Visio在“*形式”UML中预先记录软件结构(项目的“隐喻”,组件相互关系,外部系统)。然后将它们嵌入汇合中,如果有人想要打印输出,可以将其转换为PDF。
#17
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.
LyX是LaTeX的WYSIWYM前端:你可以获得文档处理器(有点类似于Word)的便利性和LaTeX的一致性和强大功能:它不会妨碍你,可以做很多专业作家需要的东西。
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).
注意:正确答案取决于您的思维方式 - 我们无法为您做出决定。如果您将文档视为文档并希望将类似于Word(Word很好)的内容与Word不相似(Word对程序员不利),那么这个答案只是显示了一个很好的选择。
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.
但是许多程序员对文档的看法不同,因此更喜欢不同的隐喻。我自己在几年前遇到了同样的问题,与LaTeX合作(因为我是一名数学家),找到了LyX并最终选择了我自己编写的Wiki / Source系统。
#18
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是任何意味着以最有效的方式编写纯文本的解决方案。如果你需要格式化,那么使用XML,Latex或类似的东西(在Vim中)。
Vim changed my life!
Vim改变了我的生活!
#19
Simple answer: LaTeX sounds like just what you are looking for.
简单的回答:LaTeX听起来就像你正在寻找的。
I use it for writing documentation myself. I will never go back to Word if I have the option.
我自己用它来写文档。如果我有选择权,我将永远不会回到Word。
#20
At phc, we started with latex, then moved to docbook, and have settled (permanently I hope) on Restructured Text/Sphinx.
在phc,我们从乳胶开始,然后转到docbook,并在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.
选择乳胶是因为我们是学者,乳胶是首选工具。我相信它没有产生足够好的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.
Docbook被选为权力,但它非常笨拙。它让我们不写任何文档:代码必须手动格式化,我们一直忘记语法,而且很难阅读。学习曲线也很陡峭。
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.
最后,我们使用sphinx转移到reST,这是一个很好的决定。文档现在非常容易编写,PDF和HTML版本看起来都很漂亮(尽管PDF可以进行一些自定义)。它也很容易定制。
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).
关于reST的最好的一点是,它的源代码形式是人类可读的。这是一个很好的优势。我现在转而使用reST来处理我所有的东西,尤其是网络上的任何东西(当然除了学术论文,除了乳胶之外,使用任何东西都是愚蠢的)。
#21
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.
您可以在http://www.doxygen.nl/上查看doxygen,看看他们的好例子。在这种情况下,文档由源代码中的注释中的标记显示。
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.
另一种选择是使用来自http://trac.edgewall.org/的trac等在线系统,这是一个生活在颠覆之上的wiki / doc / issuetracking系统。