Clear specs: Audience
clark.evans at manhattanproject.com
Mon Feb 8 17:24:16 GMT 1999
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.
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;
To subscribe to the digests, mailto:majordomo at ic.ac.uk the following message;
List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)
More information about the Xml-dev