What is a good tool for writing a user manual (help file), which integrates with version control [closed]

StackOverflow https://stackoverflow.com/questions/152241

Question

The people writing the user manual are not necessarily programmers, and they need a visual editor. A major issue is the internal format of the authoring tool; it should be readable text/html, so it's easy to compare versions of individual pages checked into version control.

Was it helpful?

Solution

There are other professional products which allow help file writing and they have support of "context ID" which makes context sensitive help possible. Doc To Help and RoboHelp are these type of products.

OTHER TIPS

DocBook

alt text
(source: docbook.org)

Microsoft HTML Help Workshop can be used to create good quality professional CHM help files. All you need is a bunch of HTML files. The tool "compiles" all these and bundles into a single Help file. The HTML files can be generated using Microsoft Word/Frontpage or even Dreamweaver. You might want to consider source controlling these HTML files.

Latex. Lyx provides WYSIWYM for writing latex files.

At my old job they used a tool by madcap software called flare.

It seemed to work really well.

A good combination to consider is Subversion, DocBook and Publican.

At the moment, this is one of the toolchains in use by the world's largest provider of open source solutions, and the name behind much of the world's use of Linux-based operation systems in the enterprise market. Most (and close to all) of Red Hat's official documentation is created in such a manner. Same goes for Fedora.

The major "pro" here is that these are freely available tools, with a strong overlap in the market of technical writers. All of which will be able to (but might not want to) write in XML, and picking up DocBook is like picking up HTML in the 90's. Subversion is a very common version control tool, that like DocBook is relatively easy to implement and use. Publican is a great publishing tool that can take DocBook XML, and publish it to PDF, HTML, HTML-single, etc. Obviously your writers can use a WYSIWYG like Serna, but I use snippets in Geany (on Fedora) or TextMate (on OS X) personally.

The major "con" is the perception of technicality. Your writers might want WYSIWYG (and can have it), and depending on your documentation needs, this might be what you end up using. As you would know, there's a market out there for "Technical Writers" who specialize in fixing Microsoft Word styles (and markup), so the arguments for separating "authoring" from "publishing" are based on proven but distinct use cases for organizations that require documentation to be held up to the same standards of the engineering/programming/source production.

Some of the extreme advice you will get comes from people and companies that have been exposed to the value of XML documentation, and especially those in the realms of DITA, where certain multi-nationals have a reputation for acquisitions that are influenced by the format and availability of the product knowledge. there are also the arguments that locking your documentation into a "sticky" or closed format doesn't help the future maintenance requirements. This is where the open source options gain support on a corporate level. Plus, obviously, it's free.

You can use Subversion and MGTEK Help Producer. Help Producer makes help files from Word documents. TortoiseSVN comes with scripts to compare different revisions of Word documents, in Word itself (Word has a version compare tool).

Your users are going to want a visual diff tool that resembles the one they are editing in. If they are just slightly not-technical, DocBook or Latex aren't going to work (I've tried giving my users both, and I even tried Epic Editor as a DocBook editor which is very expensive but didn't work out very well after all). Sticking to something they know (Word) will prevent you many headaches.

I was very reluctant to go this route at first too, because I wanted a solution that was more 'technically perfect', but I realized over time that having happy and productive users was more important. Just saying that I know where you're coming from, but try the Word route - it works much better in practice than all the 'pure' text-based solutions that are out there. Regular users don't like markup based editing.

If you're using Visual Studio, take a look at SandCastle - http://www.codeplex.com/Sandcastle.

There's also a couple of tools that help you build sandcastle files, try searching "sandcastle" on codeplex. One of them is SandCastle Help File Builder (http://www.codeplex.com/SHFB), but I've never used it so I don't know if non-technical users will be happy with that.

Mapcap Flare is the best commercial tool around. Written by the ex-developers of Robodoc

I created a documentation system called Mandown (Markdown/Html/Javascript/file-based relatively linked documents for portability) which would easily go under version control. The visual editor part you would have to figure out separately - I sometimes use HTML-Kit which at least has a preview feature.

See What is the best way to store software documentation?

Here's another tool to check out: Xilize

We are using APT. It integrates well with the CI (standard build artifact) and is more alive than for instance word document. It is also possible to generate PDFs and other formats when needed.

Licensed under: CC-BY-SA with attribution
Not affiliated with StackOverflow
scroll top