Jason L Tibbitts III <tibbs@hpc.uh.edu> wrote:
> WH> But just for the sake of argument, suppose that I spent some time
> WH> reading the code for 2.0 and compiled a bunch of notes about the pieces
> WH> and how they fit together and stuff like that, in what form might any
> WH> hypothetical reader want the documentation?
>
> Text or POD is what I'd prefer, simply because it's simple and there's
> rarely a need for anything more involved. If you're doing something fancy
> which needs graphics then use whatever you feel like (see the VCG-based
> graphs I generated for the module dependencies). And since I plan for any
> and all useful user and owner documentation to be available from within
> Majordomo, so nobody can claim not to have access to list-owner-info, I
> suppose it really should be text. (Though an argument can be made for HTML
> with Majordomo internally converting to text, so that a web interface gets
> some goodies almost for free.) BTW, the method for all of the
> documentation to be incorporated is already there. The help command takes
> arguments and can return an unlimited number of documents.
Well, in my experience one of the most important things to document
is the BIG PICTURE, the view from 39,000 feet. I've found that the
details down in the code make a lot more sense if I know how the pieces
are supposed to fit together overall. So when I look at a documentation
problem one of the first things I try to figure out is how I'm going
to communicate the overview. This usually ends up requiring some kind
of graphics, since a picture really seems to make the overall flow
easier to understand.
Another issue with documentation is, how will the reader use it? In many
cases the documentation for a package like Majordomo is used by a harried
list admin who can't figure out how to deal with a certain unusual
situation, and wants to enter the documentation tree with some kind of
problem description and find out what to do about it as quickly as
possible. In my experience, the typical list admin is versed more in the
subject matter of the list than in computer arcana.
For an example of how I've tried to approach the problem (well, at
least the second part of the problem) have a look at
http://medstat.med.utah.edu/medstat_ops
and click on Mail->Majordomo Manages Mailing Lists
This section is intended to be organized in such a way that a list admin
with a problem can find the solution fast. That said, getting real live
feedback on how well it works is like pulling teeth ...
That document is available in two forms, HTML and PostScript, take
your pick. I did it with LaTeX and latex2html (which is buggy). Writing
raw HTML would take care of the bug issue, at the expense of the
PostScript version. Personally, I like a real paper document when I'm
doing a lot of reading; screens just don't seem to have the readability
to support hours of staring at a document.
Text and POD are indeed simple, but I'm not clear that they have enough
tools to show the relationships between different parts of a big software
package clearly. I've written quite a bit of both and never been happy
with the tools.
One possible approach: I could update this document for Mj 2 and see
what people think of my work.
I got the latest "pre-alpha" of Mj 2 installed on my machine but haven't
really dug into it much yet.
-- Walt
-------
"If this is comfortable for you, you aren't pushing yourself hard enough."
- Lonnie Burton
"If you don't like those ideas, I got others." - Marshall McLuhan
Follow-Ups:
|
|
