Clear specs: Audience

[Clark Evans]

If it's of any value, I've always seen 4 types 
of documentation (partitioned by audience):

a) Business Process Documentation

This type of documentation describes what the business
purpose for the system/specification is.  This is, 
essentially, a white paper that introduces the primary
ideas in a understandandable way to a general audience.
It serves as a good introductory document for newbies.

For XML, this type of documentation should describe 
the goals.  What XML is intended to be, and what it
is _NOT_ intended to be. 

b) User Documentation

This type of document presents the material in a way
that is understandable by a user of the software 
system  / specification.  This type of documentation
tends to be more of a tutorial guiding the user
through actual practice exercises.  This documentation
usually also has a reference summary. 

AKA, teach via example.

c) System Administration Documentation

This type of documentation is aimed at people
who administer the usage of the software/spec
by a body of people.  It is concerned with
concurrency, collaboration, maintanence, 
standards, scaleability,  configuration, etc.

d) Programmer's Documentation

This type of documentation discusses the design
of the system and discusses how the/a given 
implementation would/does work.  Assume that
this type of reader has a good understanding
of formal systems... and leverage the power
that comes from formal language.  Use predicate 
logic, pre/post conditions, petri-nets, state
transition diagrams, what ever helps.  To be 
nice, footnote the language with a book/url 
to help the reader get up to speed.

Categorically ignore any complaints by "programmers" 
that can't understand the formal language.  By 
dumbing down this type of documentation you strip 
away the essence of the field and further lower
the quality standards in the industry.


--

I have always found that by dividing my documentaion
into these four audience categories has _always_ 
helped a great deal.  When you mix the audience for
the documentation, you end up with something that
is painful to read for all parties.

With SGML, you could *even* store everything in
a single file, and then extract the parts 
to create the various documents.  I havn't tried
this, but I'm theorizing that it would help 
to improve consistency among the documents...
which is always a problem.

My $.02,

:) Clark

xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev at ic.ac.uk
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1
To (un)subscribe, mailto:majordomo at ic.ac.uk the following message;
(un)subscribe xml-dev
To subscribe to the digests, mailto:majordomo at ic.ac.uk the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)