Jason L Tibbitts III <tibbs@hpc.uh.edu> wrote:
> Any kind of documentation is useful now. Please go ahead and do what you
> find interesting. Everything that can be used will be used. We will
> need to unify, but that can be done later.
OK.
> WH> Well, in my experience one of the most important things to document is
> WH> the BIG PICTURE, the view from 39,000 feet.
>
> OK, well, I may have done that but since I'm still not sure just what kind
> of view you're looking for I can't say whether or not what you want is
> there. There's an explanation of the class hierarchy (in loose terms, not
> some formal description) and a complicated trip through the set of function
> calls. There isn't a "list of things to write" that potential
> feature-writers might want, though I can see how that might be useful.
> There also isn't "an email's trip through the system". I'm much better
> suited to write these than anyone else, but that's no reason for someone
> else not to try.
In order for me to write something like that I would need to invest a lot
of time in reading your existing documentation and the code. That might
actually be good, since it would give me a little different perspective
than you now have - forest vs. trees type of distinction.
At my site there are really three audiences for documentation, each with
different needs. So I try to write for each of them.
Audience 1 is the list member, who at my site knows about enough to tell
a computer from a television. When talking to them I say things like
"I see you're sending mail from Netscape 3.01 Gold. Click on Edit, then
click on Preferences, then click on .... and remove the garbage characters
from the Reply To field, then click on OK".
Audience 2 is the list administrator, generally a professional in some
non-computer field who has a lot of contact with computers but not enough
in most cases to just sit down and write a lot of Perl (or any other
language). They can handle most situations like the one I described
above, but when they really get stuck pass the question to me.
Audience 3 is the Perl hacker who can figure out from the diagnostics in
/var/adm/messages that sendmail is running as user daemon and can't
read the list file because the file is not readable by anyone but
user or group majordom, so adds daemon to group majordom. That's me.
As far as I can see, the most immediate need is to make Mj2 usable by
a critical mass of people. For example, I can't bill clients for
something they can't use, but if I were able to install Mj2 at their
site then I could bill them for whatever enhancements they needed, thus
making it possible for me to write code and eat regularly too :-)
Right now I have this unsatisfactory choice between billing a client
to add smarts to 1.94.4 resend, then throwing it all away as soon as
we can get Mj2 running, or investing time I can't bill in getting
my arms around Mj2. My heart wants to do the latter and my stomache
is alarmed at the resulting low income :-)
> WH> This usually ends up requiring some kind of graphics, since a picture
> WH> really seems to make the overall flow easier to understand.
>
> I'm not going to say no; if that's what you want to do, feel free. But
> I've found that I can make much better use of text (especially if the text
> is right there with the code, as with POD) and I personally can write reams
> of text before I can draw a square (since I type at 100+ WPM and can't draw
> a straight line).
For calls to library routines, I heartily agree - especially since the
POD is right there next to the code, thus giving you an incentive to
update them simultaneously.
> But again, as always, I will not turn down any assistance. Just keep in
> mind that if you intend to write user-visible documentation (i.e. help
> texts) it needs to be usable as text. We can't pump out 100K of MIME
> attachments in response to 'help' (or 'help admin', or whatever).
Presumably if we have a list member who needs help, all we know about them
is that they can read basic email, so that's the preferred medium. Maybe
the message could include a URL where they could potentially see a picture
to clarify things, if that would be possible and helpful.
> WH> In many cases the documentation for a package like Majordomo is used by
> WH> a harried list admin who can't figure out how to deal with a certain
> WH> unusual situation, and wants to enter the documentation tree with some
> WH> kind of problem description and find out what to do about it as quickly
> WH> as possible.
>
> That sounds like the problem that a FAQ was designed to solve. So we make
> the FAQ retrievable from within the system instead of something you have to
> look up separately or you only see if you were the installer.
I've had mixed results from the FAQ files on the net. For one thing, the
FAQ for any real system tends to get huge, and less and less of it becomes
applicable to any given problem. The FAQ/document for PHP is now up to
248467 bytes. It goes on and on about Oracle, Postgress, mysql and a slew
of other things I don't have.
> Heck, we could even have a FAQ search within the code itself.
That could potentially be valuable for Audience 3, the Perl hacker.
In order to make the results meaningful to the average list member we would
need to do some serious editting.
> WH> This section is intended to be organized in such a way that a list
> WH> admin with a problem can find the solution fast. That said, getting
> WH> real live feedback on how well it works is like pulling teeth ...
>
> Well, I looked at it and it seems interesting, but I haven't needed to ask
> a question about Majordomo in several years, so I'm not the one to ask.
... and I'm no longer the one to ask, either. I'm really disappointed
that I didn't get more feedback from the majordomo-users list. By now,
with the second alias file and mail spool, my installation is too different
for the average site to get any benefit out of my document.
> The hyperlinks and such are nice but of limited use to someone driving the
> thing from behind an email interface.
True.
> WH> Text and POD are indeed simple, but I'm not clear that they have enough
> WH> tools to show the relationships between different parts of a big
> WH> software package clearly. I've written quite a bit of both and never
> WH> been happy with the tools.
>
> If I read this right you're back to programmer docs as opposed to user
> docs. To me, if it isn't part of the code then I'm just not going to use
> it.
Sure, but you know the package and how all the pieces relate.
> WH> I got the latest "pre-alpha" of Mj2 installed on my machine but
> WH> haven't really dug into it much yet.
>
> Did you actually install it or did you just untar it?
I got thru make install but haven't set up a list yet. Thought I had
a bug for you but it was just Data::Dumper installed wrong. I'll try
to get a test list running soon. Right now I need to get in some billable
hours so I can buy groceries. Wish we could get Mj2 over the hump ....!!
-- 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:
References:
|
|
