Re: Printed Documentation wirh Diamondback

From: Troy Klukewich (tklukewich_at_borland.com)
Date: 09/30/04 

Date: Thu, 30 Sep 2004 14:01:05 -0700

Hi John:

I'll try to address your points in some detail as they deserve a thoughtful
answer.

> Just google "d8 docs" and you should get most of the compaints there.
> Honestly, Xavier's book rescued me from abandoning Delphi altogether..
> however, a majority of our developers have switched to Vs.Net.

Xavier's book is great. For us, producing a print book like Xavier's while
developing online Help for a product with potential feature changes and bug
fixes days prior to RTM is no longer possible. Online Help and print books
are really two different deliverables and we can only support one now. It's
significantly easier to produce a book after a product is finished, but we
are not in that position.

Ask Xavier what it is like to produce a print book with a set deadline that
precedes the completion of a product by a couple months. That's what we
would have to do. We'd be lucky if the content looked anything like the
final product.

Our first priority is to cover the fundamentals of online Help, which is a
required product deliverable on disk. So, we need to doc the IDE while it is
changing and under development (dialogs), cover API (also under
development), document numerous new features, which change, plus update
existing documentation. We get complaints that we're not doing a good enough
job on the online Help, something I attempt to address. Adding a separate
book, which many insist must be distinct from the online Help, is not
something we can support.

Given limited time and resources, we have to make priorities and we do our
best to make the best decisions, weighing the pros and cons. More updates to
old content or more new content? More API help or more practical procedures?

We constantly weigh customer feedback, but it is difficult to make everybody
happy. Work more on existing updates and folks wanting new documentation
aren't happy. Work more on new documentation and people wanting updates to
old documentation aren't happy. Work more on API and folks wanting
procedures aren't happy.

We do our best to walk the middle road at the risk of making everybody
unhappy. :-)

>
> From my viewpoint, the manuals included with D5-7 were the best for
> reference and learning. With D8, we got some sample "how-to-dos" and the
> .Net Framework reference (all in c# and vb). How do you go from one
> extreme, to the other, in one version? D7 didn't include and API
reference
> and some help files, so my expectation of D8 upon ordering was something
> similar to that of D7. If it wasn't for Xavier, my D8 was headed for
Ebay.

There is great richness in the Win32-based documentation. Prior to D7, we
had six iterations of Win32 documentation on which to build, a larger doc
team, and literally years of content development. For Delphi for .NET, we
had one prior release to levearage: C#Builder, a smaller team working
multiple products, and a couple months of content development.

For D8, we essentially started over, almost from scratch. Other than some
ported API, the vast majority of Win32 documentation was of no relevance,
plus the product IDE was updated.

I understand that most customers will logically compare Delphi 8 to Delphi
7, which is sort of like comparing a newborn to a grandparent. Win32 content
is well matured by now. Delphi for .NET is just getting started.

For a fair comparison between product sets, give us five or more iterations
of Delphi for .NET releases and I assure that the documentation will
supercede what was done for Delphi 7.

> Furthermore, if Borland no longer wants to print manuals or provide the
> excellent documentation as provided with D5-7, then I'm assuming we should
> see a price reduction.

I'm glad you liked the D7 documentation. As I said, it took us years to get
the documentation to the point of D7, months to get to D8. The Delphi for
.NET documentation will grow, mature, and with your ongoing guidance get
increasingly better in the years to come.

Relevant Pages

  • Re: WIN32 API SOURCE
    ... The older file is found as documention for Delphi 3 and is named ... The newer file is found as documentation for Delphi 5 Pro and is ... You'll need to click on the Delphi 5 Pro link to ... you might want to try out the API Viewer at the following page: ...
    (microsoft.public.vb.winapi)
  • Re: D8 manuals - RIP ?
    ... The documentation says virtually nothing that's ... This is an area of absolutely critical importance to any Delphi ... and the first example shown is a misuse of exception ... Delphi developers have an *expectation* ...
    (borland.public.delphi.non-technical)
  • Re: My list D2007 annoyances/todos I would like to see resolved in D2008
    ... Having to scroll through it of little use since I have wade through not only other classes, but their private, protected,published methods, etc. ... I'm not sure how feasible this would be, but to be able to easily "reconstitute" my delphi environment would be really nice to see. ... I assume that CG must have had a considerable amount of IDE code wrapped up in ..net, but it seems a shame to not have the IDE written entirely in Delphi itself as before. ... Also recent fixes to the documentation is very heartening to see as well. ...
    (borland.public.delphi.non-technical)
  • Re: Which documentation tool (DelphiDoc or Doc-o-Matic)
    ... I'm currently looking at two different documentation tools ... for Delphi and I'm having difficulty deciding which one to ... pro: Fast parsing of source-code ... con: Does not fully support Delphi 2007 syntax ...
    (borland.public.delphi.thirdpartytools.general)
  • Which documentation tool (DelphiDoc or Doc-o-Matic)
    ... I'm currently looking at two different documentation tools for Delphi and ... I need the tool for Delphi 2007 and it must be able to ... pro: Fast parsing of source-code ... con: Does not fully support Delphi 2007 syntax ...
    (borland.public.delphi.thirdpartytools.general)