Last Stage of Documentation - Sun, 30 Oct 2011

You’d think making a User Guide would be easy. But there’s a bit more involved than just writing text.

I was lucky enough to be starting with a partially done User’s Guide that had already included the Welcome section and a fairly comprehsive Tutorial section. All that was left was to update these sections and to include a How To section and the Reference section. The latter would document everything in Behold, window by window, function by function.

What we’re talking about is literally equivalent to writing a book, a 200 page book at that, which must be both clear and comprehensive.

Okay, well that’s manageable. Now add in screen shots of every window, add callouts to the windows, describe each function. Decisions on how to organize everything. How to layout the pages. How detailed to get and how to set it up so that as little material as possible is repeated. When it is repeated, make sure it is consistent.

Then hook it up to Behold so that the F1 key works as a context-sensitive help function. And that Help buttons on various windows brings up the correct page. Encounter some bugs in Delphi’s help system and go back to StackOverflow to ask several questions to the resident experts to get around them.

As I’m doing that, page by page, the documentation verifies that the task is conceptually correct and is being done right. That allows me to discover all sorts of small niggly things in Behold that need correction or consistency. They aren’t worthy of mentioning individually, but they do amount to a valuable double-check and clean up.

One page at a time. A page on average seems to take an hour or so. I’ve probably done 160 of them, with about 40 more to go. Finally I see the finish line and I’m starting to pick up speed as it gets closer.

There will be one more beta version coming out as soon as those last 40 pages are done. It will include a number of changes that I snuck in, including the ability to specify a default translation file to use. After that release, I’ll do one more pass of the documentation as I add keywords on each page. Then I’ll announce when the Version 1.0 release will be available. It should have been 8 years ago, but November 2011 will have to do.

Thanks to you all for your patience and encouragement. We’re almost there.