Subject: Re: business case for mechanized documentation
From: Rich Morin <>
Date: Wed, 12 Apr 2006 21:29:53 -0800

At 9:48 AM +0900 4/13/06, Stephen J. Turnbull wrote:
> Also, maybe it would help if we think of Rich's project as
> a very-high-level code browser, rather than a documentation
> generator---comments are just one aspect.  (In this context;
> of course it is also a documentation generator.  But once you
> get dynamic, you can choose which point of view is more useful
> to you at run time!)

Kelly Anderson (off-list):
> ... a great deal of what you want is available in modern IDEs.

I have no real expertise with IDEs, but I suspect that this is
true.  Certainly, a modern IDE _should_ be able to provide code
browsing, back-link checking, indexing, etc.  However, even the
IDEs that attempt to be "language-agnostic" (e.g., Eclipse) are
not going to be up to "browsing" a complete operating system.

Just consider, if you will, the full set of man pages.  A system
browser should link into (and out of) all of these, at a fairly
intimate level.  It should know the origins, purpose, and usage
of each file in the OS, as well as capturing the structure and
function of the recognizable subsystems.

Kirk McKusick and company have done some fine volumes named:

  "The Design and Implementation of the XYZ Operating System"

However, each of these only covers the kernel.  From one point
of view, of course, the kernel _is_ the operating system.  The
rest is simply applications.  However, to most administrators
and users, the part above the system-call interface is the only
portion that is directly visible.

If you want to model and/or document "Unix", it makes little
sense to leave out the most obvious parts...

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...

--            Rich Morin     +1 650-873-7841

Technical editing and writing, programming, and web development