Re: SuSE documentation

From: Shmuel (Seymour J.) Metz (spamtrap_at_library.lspace.org.invalid)
Date: 08/02/04 

Date: Mon, 02 Aug 2004 11:45:36 -0300

In <pan.2004.08.02.00.53.32.942872@logicognosis.com>, on 08/01/2004
   at 10:53 PM, Juhan Leemet <juhan@logicognosis.com> 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
nicer.

>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
>do anything.

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?
>Who coordinates?

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 spamtrap@library.lspace.org

Relevant Pages

  • Free-ness of suse(linux)!
    ... Linux has always been free, ... However, it would appear larger companies, ie: novell, are trying to make it ... charging (for their documentation apparently) for the box sets, ... thing for suse, it's the whole point of it. ...
    (alt.os.linux.suse)
  • Re: Request For Comments
    ... a PDF file if that will help. ... The documentation will be used as part of The Freely Project's effort to ... volunteers are not always experts and are not yet in every city and town. ... we need a way to ensure that people who use the LS3 will have a 1-stop ...
    (Ubuntu)
  • Re: [SLE] Re: A better SuSE Support DB?
    ... > the publication of documentation. ... Well from this end the docs have never been an issue as IMHO SuSE has always ... or install a package knowing that the ... > individual packages that comprise SuSE Linux, ...
    (SuSE)
  • Re: [OT] An interesting view of Linuxs cost
    ... A lot of people prefer Suse over RedHats versions. ... RedHat 7.1 had a problem during boot up... ... Linux if you are sharing a hard drive. ... Not enough documentation to get a user going. ...
    (comp.os.vms)
  • Re: [SLE] docs for remote administration with VNC?
    ... There used to be some notes on VNC in the release notes, ... a short run down on what the nice guys at SuSE have done for you: ... > a really difficult time finding SuSE documentation. ... > little to nothing or outdated information. ...
    (SuSE)