Re: SuSE documentation
From: Shmuel (Seymour J.) Metz (spamtrap_at_library.lspace.org.invalid)
Date: Mon, 02 Aug 2004 11:45:36 -0300
In <email@example.com>, on 08/01/2004
at 10:53 PM, Juhan Leemet <firstname.lastname@example.org> said:
>Haven't seen the z/OS docs, but I imagine they are the usual IBM
>style. That style is quite voluminous and used to be good for
>reference, but wasn't particularly good for "learning new stuff".
That depends on your learning style. I find that when I read tutorials
I have questions that can only be answered by going to the reference
manuals. I've pretty much learned everything from reference manuals
rather than from tutorials.
>and more recently OS/2 documentation.
The OS/2 documentation, while good, is not as good as the OS/360, MVS
and VM documentation. OTOH, the help and viewing facilities are much
>Bit of a slog.
Different foks, different strokes.
>Yes, but NTP is a (yet another?) "special case". I went hunting for
>that stuff, too, recently. Turns out that there are big/heavy
>documents that explain all kinds of stuff (that you really don't
>want to know) and "therefore" the Linux crowd decided not to
>duplicate ANY documentation.
There are clients that don't require much documentation, e.g.,
TIME868. But SuSE *did* write quite a bit of text on xntp, and a
pointer to the howto plus a list of simple alternatives might have
been more useful.
>Um, yeah, I get the impression that YaST is mostly "follow your
>nose" kind of GUI wrapper to underlying configuration files and
>programs. This kind of thing might never get documented much more
>than the GUI panels and their help text.
In the case of the Changes panel in Expert Partitioner, there was no
help text. No matter what the Apple and m$ shills claim, throwing up a
GUI does not automatically make anything intuitive, self documenting
or user friendly.
>My headspace is *nix old timer
I go back farther than that, but my concern is making it easier to
migrate people off of 'doze.
>I suspect that (since it is essentially a volunteer effort?)
SuSE is a commercial distribution. The user and admin manuals are not
part of TLDP and, in fact, SuSE doesn't currently publish a channel
for suggesting additional text or changes.
>What to do about it?
1. Reader comment forms and/or electronic equivalent.
2. Solicit volunteer reviewers, as O'Reilly does.
>If they're volunteers (hence "play"?) you can't coerce them to
You can, however, solicit their input and make it easy to provide. The
SuSE community is active and large enough that I'm certain there would
be volunteers. Of course, most of the volunteers would be techies like
me, rather than writers, but I'm sure that SuSE/Novell has a stable of
tech writers to whip the prose into shape.
>Maybe an approach that pools contributions and uses them to fund
>projects? Maybe people volunteer blocks of time to contribute back?
SuSE. Of course, some of the volunteers might also be contributing to
TLDP, but my concern here is specifically the SuSE documentation.
>A place to start might be a coordinated and edited list of
>deficiencies? Immediately we're into a problem: whose "vision" gets
>to steer the ship?
Again, SuSE. It's their product, they get to set the rules. I trust
them to not be unreasonable if they set something like that up, but
they *have* to have final say about what ships under the SuSE/Novell
name. They *have* to have the final say about priorities and
allocation of limited resources.
-- Shmuel (Seymour J.) Metz, SysProg and JOAT <http://patriot.net/~shmuel> Unsolicited bulk E-mail subject to legal action. I reserve the right to publicly post or ridicule any abusive E-mail. Reply to domain Patriot dot net user shmuel+news to contact me. Do not reply to email@example.com