Documentation/Help In Delphi 2007 Part I

At lunch today I was asked by Allen Bauer to blog about one of the new to me areas of Delphi that I work on, Documentation/Help. In other words, I'm responsible for the F1 key in Delphi. I will also be discussing this topic at Code Rage. I think I'll have to break this up into a few posts due to time constraints.

There are four primary areas of the Documentation/Help system; Documentation (the doc content), Help Build (the process which converts the raw form of our content into the pretty text you read), Translation (we provide doc content in English, German, French and Japanese), Testing (validating that the context IDs are correct, doc is delivered and matches what we expect when you press F1 in the IDE), and IDE Help (meaning the F1 key in the IDE).

A few years back we made the switch from WinHelp to HTML2 Help. In this transition most of the doc content was migrated from RTF files to XML. XML is a much better format but requires a lot of tooling since the RTF files were pretty straight forward and the tooling was provided by Microsoft. But when I was tasked with "fixing F1" and after turning over all the rocks, looking under them and putting them back I found a few disturbing things out that I'm really embarrassed to even mention, but here goes. Our doc content was sitting on a server where the pubs team would just copy their modified files overwriting the old files, the help build system took over 12 hours to build one language and required human interaction to complete, I couldn't find our translated content, not everything was translated, content was missing, files were corrupt, and F1 didn't even work from the form designer.

I decided for obvious reasons to take a pragmatic approach to the problem; scientific, repeatable and well-defined. So first things first I fixed F1 on the form designer and we released a patch to Delphi 2006. Next I put all 38,000 doc files in a subversion repository and began searching through the servers to find the translated content. I'd like to mention that subversion can't handle 38,000 files x 4. Subversion may not be the best repository but it accomplishes the task of versioning the files so we'll stick with it until we can replace it with something better.

The next step was to scrap the old 12 hour help build system. Building help for all locals required someone to monitor a computer for nearly a week because human interaction was required. Since the next release of Delphi is simship (release all locals simultaneously) a full week of building the help wasn't going to fly. So we changed our build system to Doc-O-Matic. Chris White, a new Delphi R&D engineer, has been working with Tools Factory to get the Doc-O-Matic build system running and we are all very impressed with Doc-O-Matic. Currently the process is now around 3 hours and manually run each night. Soon we will get some new hardware and run four Cruise Control servers to build the help automatically each night and allow doc or translation to request a build when major changes are checked into the documentation repository. We will also add Zombie automation to verify the help works and the content.

In Part II I'll discuss the translation process, In Park III I'll give an overview of the help/documentation testing and in Part IV I'll discuss the F1 hurdles we faced and some of the new cool features.

Update After writing Part II I realised I forgot to mention testing, so I've modified a few sentences to discuss testing.

Part I
Part II
Part III
Part IV