Re: The 5 "C's"?

["Steven J. Owens" <puff -at- NETCOM -dot- COM>]

Deborah McDaniel writes:
> I was told by a former co-worker (who got it from a professor) that there
> are FOUR hierarchical c's - meaning that the value of the first is never
> sacrificed for the value of the second etc. (Drum roll...) they are:
>
>    Correctness (above all, doc must be correct)
>    Clarity (next, it's gotta be clear)
>    Concision (when possible, make it concise)
>    Consistency (this is nice, necessary even, but not at the expense of
>    any of the above)

     Hm... sounds reasonable from an academic point of view :-).
Timeliness always takes top priority in my experience, but then that's
in a time-to-market oriented situation (commercial software docs).
Abandoning the "C" theme for a moment, my priorities were always:


     Timely:  Above all, get it done in time (the worst doc is a doc
that's not there.  Okay, I'll caveat this comment - I've seen a few
docs in my career that were worse than no docs - misleading and
mistaken).  It's much better to come out with an expansion of the
documents (give them an "early release" document, i.e. a beta document
and let them order the finished document later) than to deliver the
product with no docs.

     Correct:  Make sure it's correct.  Period.

     Complete: Make it as complete as possible (if you can't be
reasonably sure it's correct, leave it out; this isn't my preferred
course of action, but when you're writing the "definitive" docs as
opposed to after-market books, corporate mentality seems to prefer
this).

     Readable: Make it as readable as possible (concise and coherent
come under this heading; so do higher-level issues like making sure
you've defined the right taret audience and written to their level,
making sure you've defined a purpose (tutorial, reference, user giude,
etc) and written to that purpose, etc.).

     Functional: Make it as functional as possible (layout, TOC,
indexing, all the little details that you might think are "cosmetic"
but in reality are a large part of what makes a technical book _work_;
referring back to priority 1, the worst doc is one that's not there,
and if you can't find it, it might as well not be there).


     Notice in the above that each successive priority implies
sacrifices that may have to be made for the higher priorities.

     Make it complete, but as complete as you can be in the time you
have.

     Make it readable but leave in something that's awkward (but
correct) rather than cut it when you don't have time to rewrite it.

     Make the index, TOC, etc, as good as possible, in the time you
have, but first make it as correct and complete and readable as you
can (layout and structure are less of an issue, assuming you're using
a professional tool like FrameMaker, and have some established
templates, paragraph styles, etc.  Not that these don't take work, but
the work is less specific to a particular book in the doc set).

     Somebody want to try to fit these into "C"s? :-)

Steven J. Owens
puff -at- netcom -dot- com


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=