Help not sufficient

Comments

• Carlo Marangoni

  April 2023 edited April 2023

  I feel your pain. I have found this to be the case with many dev's of VCL. I spend more time looking for the method then actually doing the code. There are the methods for the standard VCL then the dev's do something different. What's more frustrating is the lake of demos and if there are demos it's not commented. Then there is the long wait times for answers or when there is an answer it's a non answer.

  
  

  I would be great if the dev's provided many more examples in the documentation with comments, or with the code examples break it down into smaller examples with comments.
• Ray Cernis

  May 2023 edited May 2023

  I do so agree. I use a number of vendor tools, and LMD are among the worst in terms of help files (though very very few are even up to an "ok" standard). I know it costs money and time to develop good help, but it repays itself in customer satisfaction many times over. In an ideal world (and, in my experience, TMS come closest) what I like to see is help divided into two parts:

  
  

  (1) A "User's Guide", which explains what the components do and how to make them do it, in however many ways are available. Also describes the important properties. Very useful for people new to a particular set of components.
  

  (2) A "Reference", which simply lists all components and properties, and tells you what each does. Most useful when you're familiar with a component (or "type of component", such as "a grid") but don't know, or can't remember, which property or value is needed, and need the answer quickly.
  

  
  

  What we generally get, and definitely from LMD, is a poor attempt at (2), with about a couple of (usually out-of-date) small entries in the help file that would fit in (1). Almost always, these are created by scraping comments developers might have happened to put into the source, and are totally useless as true "help" files. The result is incomplete, missing, or out-of-date documentation (even Embarcadero "help" files are full of "Embarcadero has no further information on this topic").

  
  

  Examples are also mostly useless on their own - they're little better than adverts saying "look how cool our components are!". At best, they show me one way of achieving a particular function. But why does the example use that way/that property setting/that function? What happens if I do things differently, and what affect does that have? That's why I believe the "User Guide", mentioned above, is needed.

  
  

  It's also no excuse to say "you're a developer, read the source". With the 1000s of lines of code involved in a decent component library, and the myriad inheritances going on that's neither sensible nor even feasible.

  
  

  I grew up with IBM mainframe documentation, have led a documentation team, and used to be the Technical Editor of a computer magazine. I know what good documentation looks like, and LMD's isn't.