Monday, August 27, 2007

Help Examples

Last week Dee Elling, our documentation manager, posted Old Help and New where she goes into details about how our help has fallen short since Delphi 7. I want to elaborate with a brief overview about how we are bringing back the examples in the help and the work that has gone into that. This is item #1 on the list Dee's provided.

Before we started the process we did some brain storming to figure out what we wanted, what we could do, and problems we had with the old system. One of the problems with the old format is many examples fall short of being compilable and functional. So I wanted to provide functional compilable examples. So we set forth to build a system where we have projects similar to the Demos that compile, run and can be automated so we can verify their behavior. The side affect of this is we instantly have more automation testing.

The next phase is to go through all the Delphi 7 and C++Builder 6 help files to get all the examples, create the .cpp/.h and .pas files, create projects out of them and then add metadata in the form of easily parsable comments so we can rip out the pieces of the projects we want to show in the help files. A scanner and parser will be built which pulls out the example pieces and injects them into the .xml files before the Doc-O-Matic build process.

This will all happen automatically on our help build server that is using Cruise Control to run automation builds of all help languages daily.

5 comments:

Anonymous said...

The XML filename case sensitivity she mentioned needs a code solution as well. Not just to fix it quick, but to make sure it stays fixed in future.

Anonymous said...

It would be nice if the code examples in the help get syntax highlighted. Doesn´t DocOMatic support that?

Anonymous said...

to me the most important and most urgent thing is to write the help text of all the topics, then add the examples. So far the D2007 help is *completely useless* (see comments on Dee's blog)

Julio César said...

Please create a "Code Central way" to for the comunity can contribute with that creation of new examples, with a link to download the "comunity contributions".

Chris B. said...

Julio,

That is a great idea. It most likely will take some time but I'll see what we can do.

Post a Comment