I wrote a big response which in retrospect is not really the kind of answer
I want to give. I'll include it below just because, but I can sum up
quickly:
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.
Documentation that users (i.e. owners and members) will see needs to be
(absolutely must be) able to come across as text. Frills can be added
for web users, or users with a printer.
I have my views about what ideal programmer documentation is, but they
should have no effect on you. Create what you find useful; not everyone
will find my ideas as useful as I do.
2.0 may not be solidified enough for full-scale user documentation
development. The very beginnings I have made have are all text and
concentrate on documenting the available commands.
Note that in the large response below, I'm unsure as to whether you're
talking about user docs or programmer docs.
>>>>> "WH" == Walt Haas <haas@xmission.com> writes:
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.
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).
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).
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.
Heck, we could even have a FAQ search within the code itself. This stuff
is not difficult, but it is for later. Right now we don't know what kinds
of questions will be asked so it's hard to come up with answers.
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.
The hyperlinks and such are nice but of limited use to someone driving the
thing from behind an email interface. Don't get me wrong; it's nice to
provide something suited to the web users in addition but we cannot forget
our roots.
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. I don't want to open a web browser, I don't want to look through
sheafs paper (and if I did I'd just print out the text), I don't even want
to see someone's isolated description of how the code works. I want to see
the documentation _in_ the code. That to me is the most useful form of
documentation. If that's not your ideal form of docs then feel free to
create something that is. There's no reason for there to be only one way
to see how it works.
WH> One possible approach: I could update this document for Mj 2 and see
WH> what people think of my work.
Now I'm confused because you're talking about user docs again. I don't
think things have solidified enough for you to write that kind of
documentation for 2.0, but you're welcome to try.
WH> I got the latest "pre-alpha" of Mj 2 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?
- J<
Follow-Ups:
References:
|
|
