Re: No wonder Borland Technical Documentation stinks

Bob Dawson wrote:

....a lot of excellent ideas.

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:

Agreed - one of the most useful books I bought was Eric Harmon's
"Delphi COM Programming". If I take on a new technology, I need
hard-core detail that does not dwell on stuff I could figure out myself
in a day or two.



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.

Agreed: I would prefer a moderated approach, but using the Quality
Central model, with the Borland staff delegating specific tasks to
approved volunteers.

The lack of a wiki or equivalent baffles me - the only thing more
surprising is how long is is taking to do anything about it (caveat: I
know JK is working on something on these lines, but there is nothing
visible yet. Hopefully DevCo will not be stuck with the same lumbering
beaurocracy / dubious sense of priority that appears to prevent Borland
from progressing on any number of things)

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.

Exactly: why rewrite the wheel (if you'll forgive the mangled metaphor)?

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.

Moving from print-based documentation to a managed collaborative
on-line environment opens up a broad range of possibilities. There are
a lot of excellent articles / tutorials on the net; if there is a
relevant article on Dr Bob's site, why not link to it? If there are
partners providing add-ons for a certain object, why not link to their
home pages?


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 think that an investment in this area would allow DevCo to leverage
it's highly-knowledgeable user base in a very positive way. It reminds
me of Quality Central - I don't know how much it cost to implement
(though I recall how long it took to push through), but I am willing to
bet that it has been more than justified.

Cheers,

Ian
.

Relevant Pages

  • Re: No wonder Borland Technical Documentation stinks
    ... it's good news that DevCo is serious about hiring some ... good people to help with the documentation. ... Transitioning Delphi programs to .Net ... so the writers become a part of the scrum. ...
    (borland.public.delphi.non-technical)
  • Re: Writer suggestions?
    ... writers to produce EUD (End User Documentation). ... been whittled down a bit and those remaining are wearing several EUD ... production hats - engineering mthods and technical writing. ...
    (alt.usage.english)
  • Re: Locking Question around hashtable
    ... documentation states that you don't need any locking. ... To support one or more writers, all operations on the Hashtable must be ... the Thread Safety section itself was the standard "instance ...
    (microsoft.public.dotnet.languages.csharp)
  • Re: Why I hate "info"
    ... then that should be the subject of the documentation, ... Most programmers are neither writers nor technical writers. ... Second, umount the partition. ...
    (Fedora)
  • Re: Win32::Internet fetch url question
    ... documentation for 'timeout', ... So you looked at the documentation and found ConnectionTimeout and that didn't help disconnect the connection after a certain amount of time waiting? ... You could also look at the test code that comes with that module, ... The "GENERIC URL FETCHER" part... ...
    (comp.lang.perl.misc)