What tools does your team use for writing user manuals?

Question

Basic requests are:

• human readable / text format (for easy version control)
• online (for collaboration)
• easy formatting (markdown ok, html is too much)
• strict formatting (so authors don't invent new types of titles, bullets etc.)
• exportable to PDF, HTML
• easy backup and deployment (so we can "deploy" to customers site as read only version)

We are thinking about using some kind of wiki engine, but it would need to use files for storage or have other means of "deployment" to customer and be easy to install/maintan. Also, it would have to be free / cheap (confluence is way too expensive)

Any suggestions?

Edit: I'm not looking for tools to document code, we have that covered using Sandcastle.

Answer 1

We use help and manual for manual and help file. There is no html export, but it provides html help, winhelp, pdf and some more formats.

Answer 2

try Dikiwiki

Answer 3

We use Word. It gets put into our version control, so we have history (there's a documentation folder linked to every project). Formatting can be controlled using templates, all of which we now have set up, so making changes is easy to do within the layout standards. The files can be exported to PDF. You can publish them as read-only docs for sharing with users.

Answer 4

Although it may not answer all your requests, DokuWiki may be worth taking a look at.

As with other wikis, it has a simple syntax, and has version control to track revisions, generates table of contents, and a full-text search feature which can come handy for a help system.

You may want to evaluate the feature list to see if it will meet your needs.

Also, there seems to also be a good collection of avaialble plugins. Although I haven't used DokuWiki or its plugins, there seems to be plugins available for PDF export as well.

Answer 5

For our API, we use Doxygen, which is great.

Answer 6

We're using a wiki. I recommend MoinMoin because

• very simple to setup (even on a Laptop)
• very simple to backup (you can even commit the wiki to a version control system to sync it between, say, laptops for offline usage).
• nice syntax
• easy to extend
• Easy to search

We're not using something like Word because:

• Documentation rots too fast
• Searching all documents is a pain
• Linking between information bits is a pain
• No diff between versions
• Binary format which craps the hell out of any VCS
• No deep bookmarks
• Documents grow too big and then they become clumsy: Split (and no searching anymore) or wait ages to load.

Answer 7

LaTeX

Answer 8

We've had great success with DocToHelp. It works great with Microsoft Word based documentation as well as other forms, and it's even got some great integration features for Visual Studio.

The best part is once you've got a core document base imported into DocToHelp, you can choose any one of a number of export formats be it WinHelp, HTML Help, Java Help or the nice and fancy searchable Net Help.

Answer 9

You don't mention the language/framework that you are using. There are really good documentation tools out there, but some of them are specific to what you are developing in. We are a C# shop, so my answer will only apply to you if you are using .NET.

We use Sandcastle, which is not only free, but open source. While people primarily think of it as strictly an application that generates documentation from XML Documentation, you can provide your own content in MAML. It can target both CHM and web site deployments, which meets our needs. There are some additional tools that can provide things such as marking favorites and topic ratings to my understanding, but we have not started using them as of yet.

This provides us with both internal and external documentation. Since we also use Team Foundation Server, we use the built in Wiki on the Team Project in Sharepoint, but that is more geared towards project collaboration.

Edit: Fixed broken link, and also wanted to mention that there are other tools in conjunction with Sandcastle, that we use. Things such as Sandcastle Help File Builder and GhostDoc are common tools. The first to edit the Sandcastle projects and MAML, and the second to improve comment quality in the code.

Answer 10

For doument the code I use Doxigen. I prefer the linux version, I had have problems with a few features in the Windows version

Answer 11

For "manuals", Docbook. It's an SGML dialect designed for technical documentation. http://www.docbook.org/ . It may not meet your "easy markup" criterion but it definitely produces nice output in LaTex (can be converted then to PDF) and good HTML output if you cook up your own CSS stylesheet for it. Text files kept in version control. All programs also use a library that combines command line argument parsing with "--help" output in a choice of formats (normal, man page, and docbook). For the API reference, doxygen of course.

Answer 12

At my current we churn out single use software so documentation often gets put ont he side line and is done in word.

At my last job however the documentation team seemed to continuously rant and rave about mad cap software's product "Flare" it allows you to write in one format and publish to many mediums so your manual can also be your online help or a website, etc...

Answer 13

My company uses MediaWiki and TikiWiki for most documentation. We also have a guy that compiles stuff into MS Word and PDF formats for printing/sending to customers. I'd recommend you avoid TikiWiki like the plague. MediaWiki is great, both because it is really easy to use and because everyone knows how to use it -- it's the de facto standard wiki, and deservedly so, IMHO.

Answer 14

For some time we were using DocBook, but it was very hard to extend with more advanced, and necessary features (syntax highlighting, splitting into several files, multilinguality management etc.). Later, we decided to write our own system from scratch and release it as open-source: link text. It uses plain text files and Markdown as the syntax language, and now we have everything we need. The disadvantage is that currently there is probably no Markdown parser that produces something else than HTML output. For now this is enough, but we are thinking about implementing PDF support quite soon.

Moreover, we are maintaing MediaWiki as a community-based help.

Answer 15

I can not say enough good things about Asciidoc. It has a very simple markup syntax, can generate everything from pdf to roff, portable to implement and very easily inserted into any wiki with only a few minor changes.

Even in its markup state, its very, very easy to read. The only thing I have to fiddle with when using it are tables, but that's not too difficult.

If you keep the text formatted files in your repository, revision tracking is quite simple.

For code doumentation, I use Doxygen.

Answer 16

MindTouch has had an open source wiki for free download for quite some time and recently released a commercial version of that product specifically for technical documentation. It includes an Intelligent Documentation Framework, that provides guided authoring for common docs like FAQ's, Tutorials, References, Feature pages, etc.