Documentation, bleugh!

CaseDetective for FogBugz 1.1 is done, finished, complete … almost. Just need to get the documentation done.

It’s always the last thing to be done, we developers always put it off to the last moment and generally see it as that horrid task sent by the devil to torment us.

Except this time I’m not minding it too much for some reason.

Maybe it’s because I’ve decided to really shake up the documentation and website this time round, last time it was a little half hearted and I’m feeling I need to make a big push this time to get a much better quality set of docs there.

Since releasing CaseDetective last year I’ve had a fair few support requests that really shouldn’t have been there, documentation should have nipped them in the bud. Whether that be information on the website for prospective downloaders or in the help docs for those looking to get a little more from CaseDetective. Obviously my docs just weren’t up to scratch.

At first I’m just getting the basic documentation framework back into shape before private beta as I’m changing the way I produce them a little, it won’t be anywhere near complete but should give an idea as to the format (placeholders will abound).

Originally I authored my documentation and CaseDetective website in separate RapidWeaver files and then processed the documentation output through HelpLogic to get the final help files and separate docs website. There are pros and cons to doing this.

On the plus side it was easy to set up the documentation file so that it didn’t use any index.html files, HelpLogic doesn’t allow them as they conflict with files it has to create. It also meant I could have a nice docs website that looked and performed just like a normal help file, with searching, contents, index and everything.

On the minus side is the fact that I was maintaining two separate files which shared a lot of the same information, such as support contacts, features overview etc. Also, that separate docs website may be searchable by itself, but not from Google and other search engines as it uses frames, so does not contribute much to my marketing effort (when I actually start to do some that is). The separate docs site also doesn’t have my CaseDetective theme, it’s totally different so doesn’t look part of the main CaseDetective website. Both the searching and not being integrated into the main site are potentially big hindrances to getting free marketing from the content (when it improves) and looking professional.

So I’m now using one RapidWeaver file for my CaseDetective website and just rejigging it so that I only have one index.html, the main one which would never be included in the help files anyway.

My (new) website will have fully integrated documentation using the same theme as the rest of the site and will of course be searchable by search engines. And when building my in-application help files I simply switch the theme to a plain theme I’ve created and extract to a folder that HelpLogic will pick up from. Then I just delete the index.html file and it’s associated resource files and use HelpLogic to reformat everything for Windows and Mac help formats. A quick compile to CHM format with the free Windows HTMLHelp Studio and index the Mac OS X Help Book with the free Help Indexer and we’re ready to build the Windows setup file and Mac disk image. It takes much less time than it did to write this paragraph, honest!

Well, I guess I should get back to it, those private beta testers must be chomping at the bit by now, desperate to get their hands on CaseDetective 1.1b1!