| Why, because writers aren't programmers, and developers are under too much
pressure to send to much time with the writers. Here's a fwe suggestions,
based on my experience with the Ada writers over the last to years.
.1 Writers are aware of their problems, but often are timid about asking
developers. Get on friendly terms with your writers. Drop in to their
office and chat occasionally.
.2 They LOVE IT if you write examples for them.
.3 Try to get them to talk to you BEFORE they start on a new subject. It makes
their life easier, and yours.
.4 Developers do have a responsibility toward the manuals. Browse through them,
and keep feeding ideas to your writers.
/Bevin
|
| The reason I think it's unrealistic has to do with the logistics
of preparing examples, getting them merged with the text, and
getting them to support the text they are merged with. Then the
printed result has to get to where I can read it.
The reason I think it's inappropriate is more interesting. What
I'm looking for are 'sophisticated' examples that illustrate
the relationship between, say, 'structured programming' and DCL.
I think the inclusion of examples like these in the DCL reference
manual would *DIMINISH* the manual's usefulness to a broad cross
section of it's intended redership.
Many of the people who consult the Command Language Reference Manual
are not programmers. To suggest to them that they need to be programmers
in order to properly exploit the features of the language is to distract
them from their original problem. So it's a question of target audience.
Perhaps the 'Guide to Using Command Procedures' is more appropriately
targeted to the kind of example I'm looking for.
While I'm on the subject, many people assume that 'if the writers only
knew what the developers knew, everything would be OK'. Wrong. Of course
there's a large overlap between what the writers ought to know and what
the developers do know, but there are two significant disjoint sets of
knowledge required by each group:
1) The developers need to know things about the 'internal workings'
of the software that the writers ought not to have to know in
order to explain the behaviour of the software. Software that
requires knowledge of its internals to explain why it works the
way it does is typical of the old-fashioned, 'hacky' software
that we're trying to get away from.
2) The writers need to know what the reader's knowledge base is
*much more* than the developers do. Assuming the phase review
allows the proposed funcionality of the software pporduct to be
verified as potentially comprehensible to its users, it remains
the writer's task to turn that potential into reality, just
like it was the developer's task to turn the proposed functionality
into a reality.
Dave
|