Subject: Re: business case for mechanized documentation
From: Rich Morin <rdm@cfcl.com>
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.


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


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

-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