At 18:02 -0500 2003-08-02, Earl Hood wrote:
The implication is fairly direct when the doc states:
NOTE: You should be logged into the archive account when installing
mharc.
mmmmm. Wrong location for this note. Much too easy to skip over and not read.
It's under "Extracting". I can extract as anyone. I usually extract as me.
Anybody with more than 2 weeks of experience with software packages knows
how to extract a .gz distribution.
This note belongs under "Running install.pl" or under "Introduction" but
it does NOT belong under "Extracting mharc"
Yep, under "Configuration Check". It states to examine lib/config.sh
and make any edits as needed.
Examples examples examples. Tutorials. Information is desperately needed.
Life is too short to second guess the mind of the developer..
I made the edits I could guess were "needed" but I didn't know what I needed.
There is an assumption that the user
will check the comments and each variable in the file.
There is also an assumption the user will know what is "needed without
hints and examples. I maintain that the latter is a faulty assumption.
Let me be more clear. I didn't ask if I must have multiple users but if I
_could_ have multiple users. That's orthogonal to need; that's "desire".
I do not understand your question. Are you refering to people who
access the archives via the web or are you talking about mharc users
(i.e. the admins)?
Neither. I'm talking about user accounts subscribed to mailing lists.
Obviously mharc was designed to make things "simple". I'm beginning to think
that for my purposes it's actually too simple. I suppose if I had hundreds of
mailing
lists to archive in a central archive location on the web, mharc would be an
excellent
way to handle things, all in one place. But that's not what I have.
I have one or two or a few lists (lists that I don't maintain) that I want to
archive.
List archives would be stored separately on their own web pages under
different
URLs for different (virtual) hosts.
OK, so it appears that I am recommended to
1) create a user, fred (mailarch, mharc, marcV, whatever)
2) give that user a home directory
3) use that home directory (o0r a subdirectory of it) as SW_ROOT
4) get mharc configured
5) subscribe my user (fred...) to the desired mailing lists
These steps seem to be missing (explicitly) from the docs; if I simply
missed
seeing them, I would appreciate a pointer to their location.
These explicitly steps are not mentioned, but can be implied.
urm. Again, implication is a waste of the user's time. Five minutes of
explicit
documenting can save hours of questions later.
I didn't say I can't figure out how to administer it. I can't figure out
how
to use it. There are all sorts of cgis in a subdir oof $SW_ROOT. How do I
use
them? What are they for? What's the "Getting Started" example? How do I run
things and make a page on the web? How do I find and access that page?
There is a section called "Web Server Configuration" on how to configure
the web server.
That's server configuration. Server configuration is administration.
I'm talking use.
What URL do I tell people to type in the little box at the top of their
browser in order to get to the appropriate archive?
The only thing missing in the docs in the issue about configuring
the server so that the ROOT_URL in config.sh actual works.
Well, that's a biggie :-)
If mharc >is installed under a web accessible directory,
Other than the statement
list administration messages are never in a web accessible location.
I don't _see_ anything about installing in a web accessible location
(an example would be installing it under the public_html directory of the
archive user account).
A most excellent example; sadly, an example not provided in the doc :(
If not, the server will need to be configured.
Basically, defining an Alias directive should be sufficient.
Examples are good things. This one belongs in the sample apache.conf template
All the CGI related configuration should already be handled by the
etc/apache.conf template provided.
Again, I'm not talking configuration; I'm talking use. Are the cgis called
"behind the scenes" or are they ever typed in a URL:?
Stating these things explicitly in the docs would be good....
I may be obtuse, I may be missing things, I may have an imperfect
understanding of the mhaarc Gestalt, but I'm not a general newbie. Maybe if I
was a newbie I'd commit the install doc to memory before trying anything. Or,
maybe I'd give up. I doubt I would guess all of the implied knowledge I need.
I'm not a newbie; I'm a 20-year *nix veteran with a lot of QA and
documentation experience and a lot of experience writing (and testing)
installation guides and tutorials. Explicit information is good. Implicit
information is bad.
That 20 years of experience tells me that if I miss something it's because
the thing I missed is either
not present
or
in the wrong place
or
inadequately explained
I realize how difficult it is to write clear docs; the writer invariably
understands the entire process as a whole. The writer fails to notice what
information is missing, believes that implicit knowledge is easy to grasp.
Unfortunately, this is a common pitfall for writing docs.
Thank you for the additional information you have provided in answer to my
questions.
I expect I'll be using MHonARC "straight up", however.
--
- Vicki
Vicki Brown ZZZ Journeyman Sourceror:
P.O. Box 1269 zz |\ _,,,---,,_ Scripts & Philtres
San Bruno, CA zz /,`.-'`' -. ;-;;,_ Perl, Unix, MacOS
94066 USA |,4- ) )-,_. ,\ ( `'-' http://philtres.com
mailto:vlb(_at_)cfcl(_dot_)com '---''(_/--' `-'\_) http://www.cfcl.com/vlb
---------------------------------------------------------------------
To sign-off this list, send email to majordomo(_at_)mhonarc(_dot_)org with the
message text UNSUBSCRIBE MHARC-USERS
