Subject: RE: business case for mechanized documentation
From: Rich Morin <rdm@cfcl.com>
Date: Thu, 13 Apr 2006 11:24:14 -0800

At 10:29 AM -0600 4/13/06, Anderson, Kelly wrote:
> Again, you are switching from user documentation to programmer
> documentation and back whenever it seems to fill the need of your
> current argument. I strongly suggest that you draw a clearer
> distinction between the two for purposes of this conversation as
> they are quite different, especially from a documentation
> generation system point of view.
>
>> In summary, a documentation system that proposes to cover an OS
>> (e.g., Linux, Mac OS X, SomeBSD, or Solaris) needs to cover all
>> of the topics that the man pages do, and a bit more.  So, an IDE
>> (by current standards) won't cut it...
>
> Of course. That's USER documentation, not programmer documentation.
> Two different animals.

I don't think you understand what I'm trying to do.  As a result,
you keep assuming that it matches your pre-conceptions of what it
should be (e.g., IDE, documentation generator) and criticizing me
when I discuss possibilities that lie beyond those constraints.


Clearly, there are differences between the documentation needed by
a user, an administrator, an applications programmer, a systems
programmer, etc.  There are further distinctions that apply to
types of users and administrators, etc.  When I have the luxury to
consider these differences in writing a document, I do so.

However, if I am building a large-scale information resource which
must serve the needs of a broad spectrum of users, I don't have this
luxury.  Like the writers of the Unix man pages, I must focus on the
nature and organization of the system being documented, presenting
it in the clearest manner I can.

A survey article in Scientific American and a paper in Nature will
have great differences, based in part on their expected audiences.
A definition in a dictionary or an entry in an encyclopedia, in
contrast, cannot customize itself to a particular audience.

Similarly, a knowledge base/documentation system that will be used
by a broad spectrum of users will only have a limited capability to
customize itself for the needs of each user.  Being dynamic, it can
tailor the "view" presented (e.g., leave out information that goes
down into the kernel, if the user is not interested in that), but
the basic "model" of the operating system (and the text about any
particular aspect of the system) will remain the same.

Modeling an operating system, at any useful level of granularity, is
a substantial undertaking.  The writers of IDEs and documentation
generators recognize this (implicitly, at least) and constrain their
ambitions in order to meet a narrower set of needs.

Similarly, because I'm not trying to create an IDE, I can ignore the
kinds of issues that are specific to them.  I can also generalize on
the capabilities of documentation generators, because my focus is on
entities and relationships, rather than (say) functions and structs.

-r
-- 
http://www.cfcl.com/rdm            Rich Morin
http://www.cfcl.com/rdm/resume     rdm@cfcl.com
http://www.cfcl.com/rdm/weblog     +1 650-873-7841

Technical editing and writing, programming, and web development