Tales from the Scene #7 - Marco Polo

Your reviewer was looking at a funny post on a certain forum:

"Marco Canto has released an updated version of his "handbook" for Delphi 2010. ...
Does anybody have it and is willing to share ?"

For those who are uninformed, Marco Polo refers to the game of Marco Polo. In context of programming, it means:

1) You use Delphi and stumble upon partially documented or unknown feature
2) You find a feature that is "new" in Delphi 2009 or Delphi 2010
3) It's not in the help file, or the files were removed, or the only explanation is 1 or 2 postings on Google Groups.
4) You wonder what this feature is used for.
5) You try to use it, but eventually fail because of bad or extremely poor documentation
6) You ask around your friends, they never used it or even heard of it.
7) You wonder if you are the only person in the world who uses Delphi?

Example #1 - There's this new feature called "Class Constructors". The only place in the whole internet about this is Oracle at Delphi. and the first comment #1 is "I'd like to see this in Delphi Help" but it's not there in the Delphi help files. In fact, there is almost no documentation for this and you are left scratching your head if this is a new feature or some marketing buzz?

Example #2 - The only place with lots of information about IDE is in Mr. Christopher Benson's Blog, Macro Cantu's Delphi 2010 handbook. Maybe they should put his blog, book, or anything else important into the help file, so it does not look thin and pale.

Example #3 - There's this new feature called "multiple build" but no clear way to make all the DPR files's compile settings in a group all similar?

Example #4 - The most amazing ActiveX feature not found in Delphi is ActiveX property persistence. There is not even 1 single good post in the whole Internet about this - just anecdotes, discussion, obsolete tips, pointers, half codes.

Maybe nobody in the whole world maybe except DelphiHater who tried to write professional ActiveXs using Delphi and hit upon a brick wall which seems to make Delphi seem useless.

Example #5 - There is literally no documentation how to use Delphi resultant EXE files with Citrix. Citrix is used by thousands of corporations and no single good how-to or best practices information.


Example #6 - there are dozens of new units in Delphi 2010 and mostly 1-line explanations. Even the help file is mostly 1 or 2 lines per procedure. The old Delphi 7 help had 1 example for 1 procedure and very useful.

Marco ... Polo!
The whole idea of programming with Delphi becomes playing a game of Blind Man's Bluff, where you have to constantly search for this, that, and try to get ideas how to get things done.

With such help files, your reviewer thinks this will happen:
1) New Features with not much help. Nobody will use them. The component vendors will not use it because of backwards compatibility. There are still customers using Delphi 6/7/2005/2006/2007.Why use something specific to Delphi 2010 when everyone else uses Delphi 2009, 2007, 2006, 2005, 7, 6?

2) The help files could get much worse. More new and newer features but no clear instructions how to use them.

3) Delphi Book sales are so low, if you compare NET, PHP, Python, they have very detailed and documented help files. Maybe Embarcadero cannot afford to hire documentation specialists?


4) New people who want to learn Delphi, find they cannot learn Delphi quickly enough because of bad helps.

5) Component vendors may even feel the same. RemObjects Prism suffer from the same. LMD latest VCL component - docking components comes with 3 pages of help files. Amazing! There will come time when maybe there are no help files with the component.

6) Anyone who complains about help file, TeamB will discuss this. Maybe there should be embarcadero.help.wanted.to.improve.documentation newsgroup instead.

:)