Wednesday, February 28, 2007

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

4 comments:

Lars said...

To be honest, I still use the Delphi 7 Help Files whenever I need to look up stuff... especially the documentation of methods and properties has been a huge step backwards, since the html-help, because now there are usually no way to just click on an enumerated type (for example) and see it's values. In the good'ole'days everything was cross-referenced...
...another thing was the simple "in which unit is this declared" on top of most topics in the old help... that's gone now too...
I am really happy that you guys are putting some work towards this area, 'cause it really needs some attention IMO...

Craig said...

Can this possibly be true? Doc-O-Matic charges you a huge premium for using their tool in an automated build?

Let's see. Their server build license is $3499. That includes three professional licenses, whether you need them or not. Three pro licenses go for $560*3=$1680. Hence the cost to fully automate your help build is $1819, roughly the cost of a Delphi 2007 Enterprise license. This presumes you actually need the three Pro desktop licenses; the build cost is higher if you don't. That's insane!

Chris Bensen said...

Lars,

I completely agree with you. We have heard our customer's complains and have put a lot of resources behind making the help what it should be. The cross referenced help is very high on our priority list. But we have to start out with baby steps :)

Chris Bensen said...

Craig,

For a small shop this might be expensive, but for the size of Delphi's help system Doc-O-Matic is well worth the money. It would be far more expensive to hire an engineer to do what Doc-O-Matic does for the price. I suggest trying out the trial to see if it works for your situation.

Post a Comment