What tools does your team use for writing user manuals? [closed]

Answer 1

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 2

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 3

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 4

try Dikiwiki

Answer 5

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 documentation, I use doxygen.

Answer 6

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.