Improving Delphi documentation

I’m a big fan of The Daily Grind and a post from Friday Mike linked to this blog post which talks about Microsoft adding wiki like support to MSDN online documentation. I’m hoping that moving towards online documentation that supports some level of community contributions is an area in which CodeGear can distinguish itself.

Back when I was in QA I wrote several automated GUI test suites to test Delphi documentation including all IDE dialogs as well as all properties, methods and events for the VCL/RTL. The suite launched the help (then WinHelp), selected all of the content then copy it to the clipboard so it could further verify that the expected content was retrieved. The test covered properties, methods and events (PME’s) by parsing the Pascal source code, using a Pascal based parser originally written by $g(Anders Hejlsberg), and keying each PME into the code editor and pressing F1. The test would then search for the declaration of the PME in the help and compare it to what the parser had found to verify that the correct page appeared and that the declaration matched.

I worked closely with a few of the doc writers and in particular Janet Delu, to keep the test running and  log failures. Janet was particularly interested in VCL/RTL framework coverage did a great job filling the voids that existed. When I see people today longing for old Delphi content I think of all the work she and numerous other writers did to improve our documentation. Unfortunately, much of their effort was “lost in translation” when the doc team’s management changed and the entire team turned over.

These days there is a great deal of focus on improving our documentation and everyone’s aware it’s a critical issue. Fortunately, documentation was identified early on during the preparation for the divestiture as needing attention and numerous positions where opened and the rebuilding process begun. In fact, I have a meeting on Monday with a new writer to go over some VCL documentation.

Fixing the documentation won’t happen overnight though it’s one area among many where I see CodeGear having a huge affect.

4 thoughts on “Improving Delphi documentation

  1. For me, it’s not only the content, it’s also the help system that has become worse. In D6, I could hit F1 and was almost sure that the help would find the correct entry, or at least come up with a list of close suggestions.
    When I hit F1 now, more than not I get "Thema nicht vorhanden" (Topic missing), and I’m damn certain there exists an entry for "TMemoryStream"!
    (Note: I’m comparing D6 with D2005. Situation could be already improved for D2006/Turbos.)

  2. Steve, the Delphi help wiki has been proposed by the community for a long time (probably ever since the "updated" help appeared as a result of the changes you describe). There *is* a community-driven delphi wiki at http://delphi.wikia.com but it suffers badly from not being legally able to use the "official" documentation as a starting point.
    I’d love to see Codegear allow reuse of the BDS documentation in some way.

  3. Hi Roddy,
    I’m aware of the discussions of a public Delphi help wiki and I’ve been pushing for something along those lines for several years. We’re now in a better position to make this sort of thing happen than we had been in the past so I’m hopeful this can be an area addressed sooner rather than later.
    As for allowing use of our documentation I’ll ask so I can understand the issues.
    -Steve

Comments are closed.