What's the Best Documentation Format for a User-Guide?

Question

I know this is pretty subjective, but here it is: what documentation format (e.g. PDF, CHM, etc.) would you recommend for the user-guide in a small-scale, open-source application? Is this really just personal choice/preference, or are there compelling reasons to choose one format over another?

For clarity: I'm not asking about tools for writing documentation, nor am I asking about how to write a user-guide: I'm having a hard time deciding on the documentation format itself. Are there reasons not to use a PDF? CHMs can offer a nice indexing/searching mechanism, but is this overkill for a small, open-source application? When working on a project, was there a reason you chose a particular format?

For context, this user-guide is for a Linux-based flashcard application I've been developing in Python which uses spaced-repetition to facilitate learning over an extended period of time. I don't have a web GUI for it yet, though this might be included in a future release. This helps narrow down the options (no .doc files and a web-based approach is probably out), but there are still a number of possibilities and I'm not sure how to narrow them down.

Answer 1

HTML, single page.

Easy to search, easy to read. PDF and CHM both require apps to load, but I always have my webbrowser open :)

Answer 2

I think well-formatted HTML with next/previous page links, and links to the table of contents on every page is the best form of documentation. HTML is just plain text, so it's easy to search, and browsers can easily search too.

PDFs are too heavy-weight. CHMs seem clunky to me.

Answer 3

HTML is always a friendly choice. Ideally personally I like to give a choice between HTML and PDF.

Answer 4

I always like it when I am given a choice, at least between HTML and PDF. Add in Word or something google docs can easily import, or .ps or latex and I'm even happier.

You should be able to find a system that lets you write-once publish-many.

Answer 5

As CHM does not work on Network Shares (without some configuration that should not be needed - it's a help file after all, they are supposed to always run with no extra magic), I avoid it whenever I can - see also my slightly related question.

PDF is quite common because everyone nowadays has a PDF Reader, so I use that.

Otherwise I'll use HTML Files if it does not need to be printed, or RTF if the format is good enough for your needs.

Answer 6

Another vote for HTML.

I would also add that you might consider using a wiki format. You said its a user guide, so it would benefit from community inputs and edits.

Is this really just personal choice/preference, or are there compelling reasons to choose one format over another?

It a personal choice. The only reason to choose one over the other is the target audience.

Are there reasons not to use a PDF?

Developers would hate pdf documentations (again this is just preference on the developer) since it doesn't allow copy-and-paste. Users might enjoy it since it allows them to print the document as it appears on screen, but then again, not all users have a fast loading PDF reader. Some might dread seeing the splash screen of their PDF reader for 10 seconds just to have a quick check on the documentation.

CHMs can offer a nice indexing/searching mechanism, but is this overkill for a small, open-source application?

Its not overkill. Indexing and searching is fast in most documentation tool that it shouldn't be an issue in choosing a documentation platform.

When working on a project, was there a reason you chose a particular format?

For a close-source project I worked on, I chose Wiki documenation because my targets are developers. They can add and modify the wiki as they change the source code.

In addition, some of our designers (who are more visually gifted than the developers) were able to create nice looking user documentations that doesn't even look like the developer wiki but still uses their constantly changing information. We kept showing this to our non-technical staff so they would understand what we are actually doing (although, imo, they are more interested in the pretty pictures than the technical aspect ;)

Answer 7

I used to use CHM and have lived to regret it. CHM will most likely not be readable on most non programmer Windows machines (without an additional install) and is certain not readable on OS X or Linux machines. There are also security issues with CHM files.

Other posters here seem to believe that PDF is not searchable which is not exactly accurate. Some PDF authoring systems store each page in the PDF as a raster image while others use ASCII text with special PDF formatting and placements commands. The former approach makes search problematic while the latter approach has a completely usable search capability.

For me, the question of HTML vs PDF is strictly a matter of printing. Will users need to print either all of a portion of the document? If yes, then use PDF. Otherwise, use HTML.

Answer 8

REST -> HTML/PDF

I've recently moved all documentation to RestructuredText, then using Sphinx convert it to HTML or PDF. (Sphinx seems to be catching on, I've seen a number of sites take it up resently: MATPLOTLIB, Python Module of the Week, Sphinx-List.

We used to write user documentation in Word then covert to PDF. Then, I got fed up with dealing with Word's formatting, and it's stability.

In my search for a way to separate the data layer (documentation) from the presentation layer I found REST.

I find that it provides all the features that we were using in word (Tables, Images, Index, Cross-Referencing). Rest also makes documentation more like coding. After writting, I'll run it through Sphinx and clean up the warnings/bugs.

The only issue I have is that I don't know of a good REST editor, one with a live-preview feature, and something that would point out errors on the fly. (I'm currently using Eclipse to write Rest)

I should also mention that while most, if not all, of the sites listed using Sphinx use it as part of a python project, we are using it to document a non-python application.

Other Formats we considered:

• docbook/SimplifiedDocBook -- compared to REST it seemed too cumbersome to write.
• HTML -- If I wrote html, I probably would be spending more time on css/formatting than is done using Sphinx.
• CHM -- Couldn't find a good tool package, and management of various documents seemed difficult.

Answer 9

I would create the User-Guide as a Linux-based flashcard application. Write the User-Guide first, and embed your application within the User-Guide.

Answer 10

I've never workded with it, but there is a Help browser for GNOME called Yelp.

Here is a link from the ubuntu site:

link text

Answer 11

Most of the time users only go to the documentation when they get stuck. They don't know what to do at a certain point in an application, so they go to the documentation to get an answer to a question like "What am I supposed to do now?" or "How do I do x?"

Typically, by the time folks resort to looking in the documentation they're already irritated with the application, so getting a satisfactory answer quickly is of prime importance, otherwise the irritation factor is rapidly amplified.

So a good search facility, good navigation within the documentation and preferably an index are really important. A PDF can give you all of these, but I think Web pages can do it better.

WebHelp (such as that output from Adobe RoboHelp or Madcap Flare) is a good option. It'll give you a Web version of the 3-pane view you get from a .chm file. But if something like Flare is over the top for a small, open source project, then I'd agree with MrValdez that a wiki is a great option. They're easy to create and maintain and will give you the all-important search facility. Docuwiki is definitely worth a look.