Re: A very good blog about the Delphi 2007 Help Issue

Edmund wrote:
Rod wrote::
A very good blog about the Delphi 2007 Help Issue:
http://blogs.codegear.com/deeelling/archive/2007/08/21/38290.aspx

Brilliant. Truly brilliant. I appreciate the
honesty;

Yes, it is/was one of the most beautiful blog posts which I've seen in my small IT career. (there are less (IIRC) than 20 years beating around the (programming) 'bush') so my small opinion perhaps that it doesn't count very much, but, imho, the highest level of professionalism is to reckon who you really are, not who you think you are.

That's why all our respect and gratitude goes for our "pubs manager" lady :-).
Nick, if you monitor this message, please, can you pass her our humble salute and encouragement?

but really, what exactly *am* I supposed
to do with a broken help system with BDS2006? It's
been known that CG *isn't* going to fix that.


Hummm.... really? do you are aware of
http://cc.codegear.com/prodcat.aspx?prodid=1&catid=9

Especially the latest .CHM files (ID: 24793). Till now it wasn't something which I expected and I couldn't found in these Help files. Very good work, imho. And here I want to stress that what's the most important is the _direction_ of improvement *and* the _speed_ of improvement, rather than the (static) result of help - which already is in a very good shape.

To be also 'critical' (in a constructive way), I'll dare to mention some points (good and bad) in the _present_ help system, ie. the latest .CHM files (in an approximative order of importance):

The bad: (ie. to eradicate)

- lack of examples (but I know that they're working on it - we stay tuned, but I don't know that it's advisable to hold our breath, tough... ;-))

- (relatively) big interval between help updates.

- 'Keywords, Alphabetical Listing' - it's an odd collection of links - it seems that it's a work in progress, though. But no problem, personally, I rather prefer to have these and to help to be updated more often.

- Pages "without" info. Yep, it's natural (- "a series of unfortunate events" which was before of this - this wasn't natural. But if we speak about unnatural things we can speak also about D8, D2005, .NET strategy aso.). Now it's a (re)work in progress. Also, I'll mention this as a good point. See bellow.

- No F1. Well, that's it. Alt+Tab while waiting for Highlander.

- The 'inherited' problem. Now we have all the class members presented in an alphabetical order layout which has, of course, it's merits. But perhaps, is better to present the members also (if the system permits) in an 'inherited' way (ie. grouped by the class in which they are introduced) and/or put a symbol to mark that this member is inherited. Many times is difficult to find what has a class to offer, except the inherited members - here also is interesting to mark the 'override' members, isn't?

- (As an aside:) I don't see now an _easy_ way (a utility?) to integrate (by the developer, that's it - me) different help files/sources of info from different libs/components in a (shared) searchable index.

- The VCL help is titled 'RAD Studio VCL Win32 Reference M-Z' while it contains in fact the entire reference (AFAIS). Well, perhaps I can live with this... ;-)

- The most important links are broken, ie. "What's new in RAD Studio (Delphi for Win32/.NET). Well, well, well - you must fix these ASAP! <g>

The good: (ie. to enhance, steer on it)

+ very very very navigational

+ Notes and Tips (very useful way of knowledge sharing from someone who knows the internals - especially because the notes and tips are there only when you need them ie. in the doc page in which they belongs and if the note has something in common with other pages it is repeated also there, possibly in another form - for example, in TObject.ClassInfo we have the following note:
<quote>
Note: The Delphi compiler does not provide RTTI by default. Most classes implemented in Delphi that need to provide RTTI are descended from TPersistent. If your Delphi class needs RTTI but not the full functionality of TPersistent, compile the code with the $M switch.
</quote>
Something similar is to be found in the $M reference. - well, I wish that the help to be correct... ie. to have $M & Co. on Win32 platform in Highlander... ...but this it's another story)

+ good FTS index (ie. fine grained, rich FTS index)

+ Reference by Unit

+ "How do I..." procedural help - very detailed, very good but it needs more in some areas. (Quality Assurance Facilities, IPC - Indy for ex.)

+ Together reference (which also hides inside a very nice UML 1.5 _and_ UML 2.0 reference)

+ (Complete?) list of Keyboard mappings (finally!) (both IDE & Together)

+ IDE command line switches reference

+ Pages "_without_" info. I put it also at 'good' points because, imho, it's way better to have the class diagram, element syntax, constructor syntax, prof of existence, unit aso. even if the page has "only" a "This is class DB.TWideDataSet." in the Description section, rather than a silent hole.

So, in a few words, imho, the help system will be a selling point in Highlander. Just to continue their work in the same way and not to get daunted. Yet once again a good word to docs team - we're waiting even more news (and results) from them!

Just my 2c,

--

m. th.
.

Relevant Pages

  • TAudioIO SNAFU, arrgh ak, splutter.
    ... I may need to do a re-installination of Delphi 7. ... Integer Read FWaveDevice Write FWaveDevice ... Remove the reference? ... The TAudioIO components did go in previously, it was a bit of job, but I've ...
    (alt.comp.lang.borland-delphi)
  • Re: Why would I use .NET?
    ... Reference counting is not perfect. ... ..NET has a great Regex class; Delphi does not. ... Considering the huge poll of delphi packages available out there, ...
    (borland.public.delphi.non-technical)
  • Re: [Beginner] question on Class Diagram
    ... Flight: holds flight information ... The relationship simply defines the overall structure of how individual members of each class set may be logically related. ... in UML relationships are subdivided for specialized purposes like generalization and composition. ... There are three ways to implement a relationship: invoking a FIND search on the class set; passing an object reference as a method argument; and embedding a reference to another object in an object. ...
    (comp.object)
  • Re: functions returning objects
    ... > copies all of the members of that result into the members of objC? ... > Again assuming that the copy constructor hasn't been explicitly defined, ... > using a reference to C type? ...
    (alt.comp.lang.learn.c-cpp)
  • Re: async sockets and threading
    ... and it makes those members eligible for garbage collection. ... _seems_ like a .NET bug to me. ... reference could be in the State parameter to BeginConnect. ...
    (microsoft.public.dotnet.languages.csharp)
Loading