The Old Joel on Software Forum: Part 4 (of 5)

Documenting an application

Hi !

We need to produce some documentation for our application. I can see three levels of documentation :

- The first one is the source code documentation and class/methods descriptions.
- The second one is the architecture documentation.
- The third one is the user documentation.

For the first one, we use Doxygen and are able to produce HTML, PDF, RTF, etc. documents.

For the second one, we're using Enterprise Architect, for UML diagrams.

My question is about the third one : what tool do you use ? I've heard about DocBook, which is able to produce from a single xml file different formats : HTML, PDF, which is something I want to do but I wanted to know if there are other (maybe better) tools that you would suggest.

And another question about UML diagrams : do you keep them in the fileformat you UML Tool is using, or do you produce any other kind of documents from the UML diagrams ?

Jerome

Jerome
Monday, February 9, 2004

The canonical answer to this is 'Help & Manual'.

Konrad
Monday, February 9, 2004

You might want to have a look at RoboHelp

http://www.macromedia.com/software/robohelp/

T-90
Monday, February 9, 2004

I don't think you'll ever get a single user's manual that gives users what they really need. I've always felt you need two different sets of documentation.

1) I know what feature to use, but I need the details of how to do it (e.g. a Unix man page)

2) I know what I want to do, but I don't know where to even begin (e.g. a Unix HOWTO)

Most software users manuals only address #1, and only superficially at that.

Tom H
Monday, February 9, 2004

Tom H, I agree, but IMO you only really need the second kind. As extrapolated from Joel's articles, users DON'T read, and users DON'T like to use the manual. A person who knows what they want will most likely figure it out on their own, both because it's often faster/more fun and because of pride. When a person turns to documentation, they as a rule have no idea how to go about using the software at all. And in this case they may very well be Linus Torwalds, but a good manual still needs to detail the process painstakingly. If they didn't need the detail, they wouldn't need the manual. (This philosophy is based on the assumption that the UI is decent enough for people to not need to turn to the manual to open a new document.)

When I worked as a tech writer I started out just making Word files and putting them online as HTML documents, and later on I started using MS HTML Help Workshop. It's available freely on MS's website (do some searching), it's basic but easy to use. You do need to know some HTML, but not much. It compiles to a single file with an index, search, etc, and apparently the individual articles can be referred to from the software (I'm not a programmer at all, so I would have no idea).

Flasher T
Monday, February 9, 2004

How about a wiki? Simple to create. Simple to edit. Users can add their own information and comments as they go along. Not as likely to become stale.

You'll get better recommendations if you describe what sort of app you're writing.

Matt
Monday, February 9, 2004

Well, difficult to describe my application, as it is very domain specific, but I would say it's just a standard app (something like managing bank accounts). The manuals would have to describe all the possible menus and dialog boxes as well as providing tutorials.
I don't want to use proprietary format (like Word) because the app is crossplatform.
This is why I'd like, from a single file, to be able to produce different help files : pdf, html, etc...
I also would prefer to use a free tool if possible.

As I said above, I've heard of DocBook, but I'd like to know if it is a good choice (did anyone use it ?).

Jerome

Jerome
Tuesday, February 10, 2004

DocBook is just a document format, like LaTeX. It's not a help authoring application.

You need an application that lets you enter text in the DocBook format, and then you might need _another_ application that lets you convert that DocBook text to your output formats.

The only affordable WYSIWYG application that can handle DocBook is Adobe FrameMaker, and that software is on the deathbed and virtually unsupported. And setting up Frame for DocBook is a _major_ undertaking -- you get the complexities of Structured FrameMaker on top of the complexities of DocBook.

IMO, DocBook is an "if you have to ask..." thing at this time. You probably shouldn't touch it unless you're already that kind of markup expert who is comfortable creating XML and LaTeX documents with a text editor.

Chris Nahr
Tuesday, February 10, 2004

DocBook differ from LaTeX in the way that you leave out formating, and just think about content. LaTeX has plenty of commands to let you place text, while DocBook concentrate on how you mark your text.

Formatting is standardized, but possible to change. The stylesheets have many variables that you can override. You can also get help on the maillist if you just need to have that titelpage with 12 rotating logos and a yellow dragon.

It is tailored for software documentation, with markups for methods etc. Check out the DocBook Book at http://www.docbook.org/tdg/en/

I like DocBook, I have been using it since 2000. I have used emacs but there are plenty of tools:

http://www.docbook.org/wiki/moin.cgi/DocBookAuthoringTools

Formats such as HTML, PDF, Microsoft HTML Help, and man pages can be created. (I have used HTML and PDF only).

Since it is XML, it can be stored in CVS. If you need help outside the scope of free maillists, there are services to buy.
http://www.sagehill.net/

Fredrik Svensson
Tuesday, February 10, 2004

User Documentation:

Please, please make sure that your doc/help file is not full of stuff like:

"Cust. Del. Address Type - Use this field to enter the customer delivery address type"

This is typically the result of

outsourcing manuals
having them written by people who don't understand the app
pressure from management to ship

Justin
Tuesday, February 10, 2004

Thanks for clarifying, Fredrik, that was just the point I was trying to get across: DocBook is for people who would use emacs! <g>

Chris Nahr
Tuesday, February 10, 2004

The first document should be the requirements

Gwyn
Tuesday, February 10, 2004

Tom H.'s comment:
"...I know what feature to use, but I need the details of how to do it ..." and "I know what I want to do, but I don't know where to even begin..." is right on the money! IMO, the second is of primary importance--relating to what the user might want to do, rather than the features of a new system. Using a package such as RoboHelp allows you to write the topics, link to them, and organize them in different ways so that you can give the user both. Also, RoboHelp has conditional text features and various output formats, so that you can create one project which will have some of it output as online help and the other output in a possibly different order, for a hardcopy manual.

Margie S
Tuesday, February 10, 2004

This is just my proverbial two cents' worth of advice from spending two years in End-User Documentation Hades at IBM:

1.) Allow time about midway through the end-user documentation project to let some reasonably intellingent people _who are not intimately familiar with the software_ try to figure out how to do something useful (e.g. install the software) using the documentation. Videotape them if possible. I can't stress this enough, because the ultimate business goal of end-user docs is to head off support calls. Make it easy for the user to get the info. they need, and the cost of producing the docs will more than pay for itself. The pre-release testing will highlight any shortcomings early-on.

2.) If the end-users will fall into more than one "category" (e.g. administrators vs. users), consider splitting the documentation into separate "tracks." You can always cross-link to any "common denominator" documents, which saves on dual-maintenence.

3.) If more than one person will be writing/editing the documentation, seriously consider using source control, just like you would for the code.

4.) If the end-user documentation will be written by a non-programmer, or even a programmer not intimately familiar with the software, recruit an "enforcer" to get the technical owners to review it for technical accuracy in a timely manner.

5.) In a similar vein, do _not_ allow programmers to dictate the content. A programmer might have written the most wonderful algorithm in the history of computing, but if the end-user won't ever see it, it shouldn't go in the manual. (Disclaimer: I'm now a programmer, so I have diplomatic immunity for saying that. <grin>)

6.) However your end-product will be delivered (Word document, PDF, HTML, etc.), decide on your formats and conventions from the get-go, and make sure that everyone follows them. (Example: If italics mean one thing in one document and something else in another document, it risks confusing the user and definitely makes you look sloppy.)

cubiclegrrl
Friday, February 13, 2004