Tuesday, July 27, 2004

Write on

I've been doing some documenting of my Sydney code for the past two days. I've mainly been using Notepad for this (I'm a plain text junkie) and now I've got about a dozen small TXT files on different topics.

That's fine for the time being but I can see that I'll need something more structured before too long. Even though I'm working on developer rather than end-user documentation it's important that I write the documentation with others in mind to ensure that it's understandable to myself and others a few months from now.

Writing the documentation in HTML seems the logical choice. It has most of the advantages of plain text and allows for navigation between documents and improved document structure.

What should I use to write the HTML documentation though? There are plenty of HTML editors out there, but I'm after an HTML word processor more than just an editor.

I could just continue to use Notepad but really I've got better things to do than close my own tags. I use (and like very much) TopStyle Pro for writing HTML but that's when i'm writing web pages, not documents. Like most HTML editors it makes for a poor word processor.

So why not use an actual word processor then save the text as HTML? MS Word has supported exporting to HTML since Office 97 but the HTML it creates is far too complex and bloated to really do anything useful with.

Maybe there's a simple word processor that out there that can create simple HTML files. If you know of one please let me know.

I was just about to resign myself to writing the documentation in Notepad then manually converting it to HTML using TopStyle when I remembered I had a copy of Help and Manual tucked away on my hard drive. I won this help file generator program a few years ago at an ADUG conference but I've never used it. Looking at it more closely it supports Winhelp, PDF, HTML help and straight HTML as well as several other formats. Any of the formats can be generated from the same text meaning that I could write my documentation once and then easily produce HTML, PDF and WinHelp versions. It even functions as an adequate word processor so I could use it not just as a publishing tool but as a editing tool too.

At the moment it looks pretty good but there are a few problems with it. Firstly it's strictly a single user program. If I ever involve someone else on this project only one person could ever be writing documentation at a time.

Secondly it stores it's data in a single proprietary binary format file which means it can't be "diffed" easily and will take up quite a bit of space in my version control system as it is modified.

And lastly although it supports styles within the word processor of the program it doesn't convert those styles to CSS when it creates the HTML. I guess this isn't a big problem but it annoys me to see all those font tags when CSS styles could be used instead.

So Help and Manual looks like it will make a pretty good documentation tool for the time being at least. If you know of something better suited to producing HTML documentation I'd be interested to take a look. If it's cheap I'll consider using it now, if it's not so cheap I'll keep it in mind for when I outgrow what I've currently got.


At 5:49 AM, Blogger Malcolm Smith said...

I highly recommend doc-o-matic from http://www.toolsfastory.com. You can use plain txt files as much as you like. In fact, even editing in their IDE writes back to the txt files for you. No proprietory formats. It's not cheap but you get fantastic results. It can also be used for end-user code and will parse/update source code comments with ease.

At 5:52 AM, Blogger Malcolm Smith said...

Sorry, typo - should have been http://www.toolsfactory.com

At 1:17 PM, Blogger Emlyn said...

I only hear good things about Help and Manual, but if you are determined to look further afield, have a look at http://www.helpscribble.com/.


Post a Comment

<< Home