Re: Modular documentation questions

[Susan W. Gallagher <sgallagher5 -at- cox -dot- net>]

Back in the early 90s, Edmond H. Weiss, in his book _How_to_
Write_Usable_User_Documentation_ described a documentation
process that he named "modular documentation". According to
Weiss, modular docs are layed out with a single topic per
two-page spread. Each topic is formatted identically and
takes only two pages to present. (The intro is first, on the
left, the screenshot or diagram is in the upper right, the
procedure starts here,...)

I tried it once. It was an interesting exercise in self-
discipline! My users were not impressed, however. They
thought it made their Windows software too Macintosh-ish.
<sigh> I ended up rewriting the manual before publication.

www.m-w.com says a module is:
3 a : any in a series of standardized units for use together:
as (1) : a unit of furniture or architecture (2) : an 
educational unit which covers a single subject or topic 
b : a usually packaged functional assembly of electronic 
components for use with other such assemblies

I think the key word in that definition is "standardized",
which allows Weiss' concept to stand, because if each 
component or module does not closely adhere to a basic 
model, it can't be reasonably called a module.

I wouldn't call what I write now to be modular, although
my writing does follow a basic pattern. I would think that
structured, XML-based documentation could reasonably be called modular because the XML DTD or schema would provide
the required "standardization".

My two cents.
-Sue Gallagher

> It's recently become apparent to me that I've been talking
> w/ a variety of people about modular documentation,
> but we're not communicating because we don't have
> common definitions or common understandings. So,
> I'm looking for a consensus, of sorts, about what
> technical writers mean by the term "modular documentation".
> 
> My questions (if you respond to me offline, I'll
> summarize--I'd be interested in onlist discussions
> of the topic, though):
> 
> * Do you currently write "modular documentation"? Why
>   or why not?
> * What _is_ modular documentation? (Please provide
>   examples or an adequate description for what your
>   modules look like. Are they paragraphs? Chapters?
>   Tasks? How do you tell a new writer what to create?)
> * Do you reuse/repurpose documentation modules? Why or
>   why not?
> 
> Thanks for any input you can provide,
> Eric