Software documentation
January 31, 2007 9:51 AM Subscribe
What's the best software for writing and publishing software documentation?
Yeah, and nDoc. Duh. Not enough caffeine yet.
posted by matildaben at 11:21 AM on January 31, 2007
posted by matildaben at 11:21 AM on January 31, 2007
Software documentation generally falls into one of two categories: tutorials/guides and API docs. There's numerous out there that let you embed documentation in source code via comments then automatically generate the API docs for you. The most popular of these tools, at least in the open-source world, is Doxygen, which supports lots of languages, including C, C++, Java and Python. Other popular language-specific tools include JavaDoc for Java, Epydoc for Python, NDoc for C# and phpDocumentor for PHP. Wikipedia has a page about these things.
However, I'm guessing that you're looking for tools to help you write manuals or tutorials (API docs help people publish libraries, and if you were publishing libraries for other developers, you'd probably know about these tools already). The standard language used to write docs of that nature is, unfortunately, DocBook. I consider that unfortunate because DocBook is a powerful, difficult to learn format. Fortunately, there's a number of tools out there that let you write docs in more convenient formats, then translate them to DocBook (or other output formats). My favorite of these is AsciiDoc, although reStructuredText (part of the DocUtils project) is probably more popular. I prefer AsciiDoc though because it includes a couple neat features, like sidebars, that reStructuredText lacks, and because its default HTML output is a bit prettier.
So, short answer: check out AsciiDoc.
posted by gsteff at 11:24 AM on January 31, 2007
However, I'm guessing that you're looking for tools to help you write manuals or tutorials (API docs help people publish libraries, and if you were publishing libraries for other developers, you'd probably know about these tools already). The standard language used to write docs of that nature is, unfortunately, DocBook. I consider that unfortunate because DocBook is a powerful, difficult to learn format. Fortunately, there's a number of tools out there that let you write docs in more convenient formats, then translate them to DocBook (or other output formats). My favorite of these is AsciiDoc, although reStructuredText (part of the DocUtils project) is probably more popular. I prefer AsciiDoc though because it includes a couple neat features, like sidebars, that reStructuredText lacks, and because its default HTML output is a bit prettier.
So, short answer: check out AsciiDoc.
posted by gsteff at 11:24 AM on January 31, 2007
I use a Wiki (specifically: Trac with the PDF generation plugin) to write specifications and documentation. I can link to the documentation pages for specific functions or pages from the web applications I write by simply providing a deep link into the Wiki, and I can generate individual PDF pages or an entire PDF book that's organized by topic with all of the images and examples that I've placed in the Wiki whenever someone would like a copy.
You can see this in action at www.symfony-project.org.
posted by SpecialK at 12:07 PM on January 31, 2007
You can see this in action at www.symfony-project.org.
posted by SpecialK at 12:07 PM on January 31, 2007
Almost all writing packages are equally dreadful (in different ways, of course). If you're not writing API reference documentation, you might as well go with Word/Acrobat. The main advantages of this approach are the ubiquity of the software and the (relative) ease of getting technical review feedback.
posted by crazycanuck at 12:16 PM on January 31, 2007
posted by crazycanuck at 12:16 PM on January 31, 2007
If the documentation is to be localized I'd avoid the Word/Acrobat combo because (a) Word sucks at anything beyond 10 pages (start including ToC/IX and you can forget about it) and (b) many localization vendors will charge a premium for handling Word files because of (a) and because of the way Word handles/embeds graphics.
FrameMaker/Acrobat would be a much better route.
posted by ceri richard at 1:28 PM on January 31, 2007
FrameMaker/Acrobat would be a much better route.
posted by ceri richard at 1:28 PM on January 31, 2007
List of document markup languages.
Comparison of document markup languages.
I'd definitely suggest picking something that allows you to mark up the structure such that it can then be published as PDF, HTML, or other.
Short answer: what gsteff said.
posted by Zed_Lopez at 5:21 PM on January 31, 2007
Comparison of document markup languages.
I'd definitely suggest picking something that allows you to mark up the structure such that it can then be published as PDF, HTML, or other.
Short answer: what gsteff said.
posted by Zed_Lopez at 5:21 PM on January 31, 2007
I use Robohelp X5, which is a bit aged now but still functional for creating multiple different outputs from a single source: e.g. both Windows online help files and printed docs, in different formats and with different jargon dependant on the end-user. There's rumored to be a new version of Robohelp under development (work on it stopped when Adobe took it over). Robohelp is a fairly easy program to get started with, and if you already have docs in Word format it will import them nicely.
If I was starting over I'd take a good look at MadCap Flare (written by the people who first made Robohelp.) Actually, I'll try it one of these days anyway.
AuthorIt looks good too, but imo DocBook has too steep an entry curve unless you have a consultant help get the project initially tailored for your company.
I didn't like the look of the Adobe Framemaker trial we had. It felt like a straightjacket.
If there's a branch of the Society for Technical Communication near you, it's a very useful community.
posted by anadem at 5:38 PM on January 31, 2007
If I was starting over I'd take a good look at MadCap Flare (written by the people who first made Robohelp.) Actually, I'll try it one of these days anyway.
AuthorIt looks good too, but imo DocBook has too steep an entry curve unless you have a consultant help get the project initially tailored for your company.
I didn't like the look of the Adobe Framemaker trial we had. It felt like a straightjacket.
If there's a branch of the Society for Technical Communication near you, it's a very useful community.
posted by anadem at 5:38 PM on January 31, 2007
This thread is closed to new comments.
Other documentation: MS Word or equivalent word processor of your choice.
You're going to have to be a lot clearer about what you want to do!
posted by matildaben at 10:06 AM on January 31, 2007