Help!

The terribleness of the contemporary Delphi help experience is obviously well known. Moreover, attempts to defend it have long since degenerated into self-parody. To take one particularly egregious example of the latter, recently uttered with a straight face on the Embarcadero forums: apparently, it’s OK for the TTaskDialog component to have no documentation whatsoever incomplete documentation,* since it ‘merely’ wraps functionality provided by the Windows API. The fact that this would be a reason for not documenting 90% of the VCL did not strike our valient defender of Embarcadero ineptness as a big deal — all it went to show was how truly thankful paying customers should have been for TButton and the rest being documented back in D1!

The terribleness of the Delphi help takes many forms though, by no means limiting itself to a lack of content in certain areas. Check out this code sample for instance. Where to begin?

  • In the first place, showing how to construct a new action manager at runtime so as to populate a TPopupActionMenu added at design time seems an example for one-more-example’s sake: anyone with half a brain is going to contruct an action manager at design time given all the settings to set, and a fortiori, the design-time UI for settings those settings.
  • As for the actual code, the image list component is created without an owner, yet never explictly freed.
  • While the temporary bitmap is freed, it is done so using Destroy directly and without try/finally protection. Picky? Not really IMO, especially given newbies are going to be reading it (though to be fair, whoever wrote the code gives strong signs of being a newbie him or herself…).
  • The author does not understand the TCustomXXX naming convention in the VCL.
  • The author also makes the newbie ‘mistake’ of referencing the form by its global variable within one of its own methods rather than the local Self variable. The fact that the author does this four times (and in the last, for the sake of fully qualifying an instance field) suggests he or she has not totally grasped the distinction between a global routine and a method. Naturally, this would be understandable for a beginner, what with the VCL streaming system’s war against encapsulation. But one would hope that example code put into a product’s help system isn’t going to be written by a beginner in that product, right…?
  • Last but not least, why on earth is the OnGetControlClass event of the popup action menu handled? It just looks like the product of aimless playing about by a novice (‘let’s see what handling that event does…’).

To be fair, given the sheer terribleness of this particular case, I did try randomly picking out other samples in the DocWiki’s (rather extensive) list, and never found anything nearly so bad. Maybe there’s hope after all…

* As is often the case, the last-ditch defender of Borland/CodeGear/Embarcadero actually implies things to be worse than they actually are. The documentation for TTaskDialog is in reality OK, even if it doesn’t cover the particular issue the forum questioner was interested in.

Advertisements

14 thoughts on “Help!

  1. Completely agreed. First I thought, having a simple example is better than having nothing, but all your points are right and make this example worse than having no example at all.

    • Olaf — ‘make this example worse than having no example at all’. Indeed. While it’s no where near as bad, I’m not too keen on something like the StrUpper/StrLower code sample for a similar reason, since a newbie might come to it and think, ‘well that is how you convert a Delphi string to upper or lower case’.

  2. There seems to have been a concious decision, going back to the time of D7 onward, to outsource the tedium of Help. A new help file format, inclusion of the VS help system, a Wiki, all seem to be the most convenient means to handle something that seems to have gotten away from them. The constant platitudes, “we’re working on it”, “it’s continually being improved”, are old and stale and have been since D7.
    It’s really time for Embarcadero to step up and fix it. Anyone who’s used Delphi for any length of time knows the help system sucks, they’re not keeping any industry secret by refusing to accept it.

      • No. At the risk of sounding cynical, do you have any actual evidence that doing so will be more productive than a blog post syndicated on DelphiFeeds.com? That said, part of the point of the post was to highlight a systematic failing, viz., that the code examples put in since the old ones were deleted seem to have been written by someone new to Delphi or even programming as such, which is a slightly strange situation. Or, put more egotistically: I’m confident I could have done a much better job, and in less time too given I wouldn’t have had to ‘find my way’ for even the most basic areas of the product, as a novice would.

      • I knew I was missing a standard Borland/Inprise/Borland/Code Gear/Embarcadero standard reply, thanks for the reminder. The ever popular “Have you reported that in Quality Central”

        That kind of response system never does fix the problems, what it does is to let a problem percolate until it becomes agreed upon within the community, that it is the largest and suckiest problem that is not yet fixed. Sure, it’ll get votes, and perhaps the specific example cited will get serviced, but the problem is caused by the process not the content.

  3. In the latest “Roadmap” (cough splutter) they do mention an emphasis on documentation…. sometime after they’ve done 64-bit, cross platform and a whole bunch of other stuff that doesn’t have dates or even so much as an indication of expected timescales.

    Then again, the last time they did provide an indication of timescales (Commodore being the next release after Tiburon) they missed it and further more, completely changed priorities in the meantime.

    Embarcadero are rapidly losing what little credibility remains as a viable custodian of the Delphi legacy.

    • ‘Embarcadero are rapidly losing what little credibility remains as a viable custodian of the Delphi legacy.’

      I don’t know. The extended RTTI was a great feature in the last release, but the preference for Mac over Win64 targetting isn’t looking too hot, especially if a warmed-over CLX is the library solution. On the plus side, some of the DTG/CodeGear-era flippancies have been cut out (3rdRail, JBuilder and Blackfish are all moribund, Delphi .NET long dead as a ‘commerical’ product)…

  4. If Embarcadero makes a wiki or help content skeleton that will pay 10$ for each page approved by them, and rewarding top 10 content providers with full Delphi/RAD licences, then we will all benefit. Otherwise I do not see the light at the end of the tunnel.

    • @avra — well, that would need a fair bit of administering (I assume you wouldn’t exclude non-US citizens?). The simpler approach would be to do basically what they did, which was to hire a person to write code samples — but hire someone who actually has some experience in Delphi! It just seems bizarre to me that they appeared to have hired someone who was a novice in what he or she was supposed to be documenting.

  5. Pingback: And another… « Delphi Haven

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s