Re: No wonder Borland Technical Documentation stinks

"Rick Carter" wrote

At any rate, it's good news that DevCo is serious about hiring some
good people to help with the documentation.

My read as well. If you actually cruise the careers site, it appears that
there are multiple positions listed. It's a great thing, and kudos to
whoever's behind it.

Some quick off-the-cuff suggestions to whoever gets the nod as DevCo's
documentation chief:

1. Forget traditional bookstore sales and major publishers--Marco Cantu is
about the only one left in the general Delphi market, and let's not make his
life any harder. Instead, partner with one of the newer on-demand publishers
that can deliver targetted topics economically on small runs. DevCo can
vette books for a DevCo Press imprint, and sell them directly or through
internet channels like Amazon. The key is reasonable length on a tight
focus:
Transitioning Delphi programs to .Net
Design Patterns in Delphi
ECO: Designing over an OO Framework
ASP.NET with Delphi
DB Express: Concepts and Techniques
etc.
The model of 900 pages on the B&N store shelf isn't really necessary. But I
would pay thirty bucks for a book by Nick Hodges on ASP.NET with Delphi, or
Joanna Carter on OO design, Wayne Niddery on Programming Interbase, etc. And
I bet others would as well. Focused, in-depth, reviewed by DevCo, and
200-250 pages max. You really don't need a run of 10,000 to make that work.

2. Obviously, we need a tech writer or two assigned as editor/moderator to
the on-line help wiki that JK has previously mentioned. Or make it a joint
responsibility of documentation and testing.

3. API/Object help needs help: closer relationship between the writers and
R&D team, so the writers become a part of the scrum. I've already mentioned
how valuable it is to get a good tech writer on a design team as early as
possible. The best documentation evolves with (and in some cases out of)
internal development documents.

4. Additionally, it's always bugged me that documentation always tells you
what a method does, but rarely gives any detail on limits or failure
behavior. Take a page from program by contract here: documentation should
document supported use, limits/boundaries, and failure responses. It should
be possible to write a unit test or method contract based on the requires
and quarantees information in the documentation.

5. And while I'm thinking about that, we all know that example code is
getting harder and harder to come by. It's expensive to maintain, and doc
writers aren't always in the right position to create effective demo code
when the deadline's approaching. So in addition to using the wiki for
accumulating test code, why not tie the doc writers to the test engineers?
Use what's already there: incorporate the actual unit and integration test
code into the product's documentation.

I don't know how practical these might actually be--there's nothing like a
lack of direct responsiblity to make a guy feel creative. And no doubt
whoever's in charge of this already has a list of to-dos. But from a
position of pure outsider ignorance, I'd sure like to see some of them.

I hope that the test and documentation teams are as excited about DevCo as
DevRel and the R&D folks seem to be.

bobD


.

Relevant Pages

  • Re: No wonder Borland Technical Documentation stinks
    ... DevCo can vette books for a DevCo Press ... Or make it a joint responsibility of documentation and ... writers and R&D team, so the writers become a part of the scrum. ... unit and integration test code into the product's documentation. ...
    (borland.public.delphi.non-technical)
  • Re: Printed Documentation wirh Diamondback
    ... Xavier's book rescued me from abandoning Delphi altogether.. ... developing online Help for a product with potential feature changes and bug ... More API help or more practical procedures? ... Work more on existing updates and folks wanting new documentation ...
    (borland.public.delphi.non-technical)
  • 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)