Subject: Re: X Documentation
From: Patrick Callahan (pac1@tiac.net)
Date: Wed Nov 21 2001 - 08:19:49 MST
On Sunday 18 November 2001 12:34, you wrote:
> Patrick Callahan wrote:
> > I think one thing that's missing is documentation that focuses on usage
> > rather than structure of the program. We need additional documentation
> > that focuses on the why and how more than on the what and where. Don't
> > misunderstand me on this point. We'll still very much need the
> > documentation of the what and where.
>
> This documentation is the Linux HOWTOs. In my experience with Linux over
> the years I've found the HOWTOs to be the most invaluable problem
> solving tool - because the main documentation I need is the docs to get
> from nothing to a miminum working config, from there I can work things
> out for myself.
>
November 20, 2001
The linux documentation project has
http://www.linuxdoc.org/HOWTO/XWindow-Overview-HOWTO.html
and
http://www.linuxdoc.org/HOWTO/XWindow-User-HOWTO.html
contain some of what I'm looking for. They provide high level views of X
windows for the most part. While the User Howto does get into specifics, its
limited in that it explores one possible windows setup.
Don't get me wrong, I think both of these and the other X howtos are
valuable. They just dont contain the kind of material I'm really looking for.
The kind of documentation I'm looking for is different from
program documentation and a howto. It does not limit itself to a single
program, or even to X itself. Its purpose is not to describe specific tasks.
Instead its purpose is to lay out the whole landscape in a comprehensible way
at multiple levels of detail.
What levels?:
- High level - The view from an airplane.
- Mapped level - the level of detail provided by a topographic map
- Tourguide level - the level of detail provide by a guided tour of a speciic
area
- Reference level - the level of detail provided by man pages
That's a lot. Maybe we're talking about a book or serveral related documents
here.
The basic problem is the complexity of X and the difficulty in understanding
what to do in an unfamiliar situation. There's lots of things to connect
together and lots of ways to do it. To be successful, we need to understand
what the pieces are, how they're related and how they're configured.
For example, while we need to know what a desktop manager, a window manager
and a display are and how they are related in general, but we need to go
beyond that general knowlege to specifics of how they actually work and how
to configure them to work together.
We need to know where to find the configuration files, what they contain and
how they control the various elements of an operating X window system for the
specific environment we've chosen to adopt.
The X howtos attempt to do this by providing specific examples, but therin
lies their downfall. There are lots of choices of programs that are
different from the ones you find in the howtos. If you want to make
different choices, or if different choices have been made for you by your
distribution, the howtos offer no specific guidance. For example the User
HOWTO talks in detail of xdm while my box is using gdm. The overview
mentions gdm and kdm as a footnote, while the user howto doesn't even mention
them.
Here's what it should include:
- some of the high level view like you find in the X Window Overview Howto
- a parts list: complete listings of current alternatives for such things as
window managers, Desktops, locations for configuration files
- commonly used alternative ways of starting x
- details of the relationship between X, the window managers, Gnome and KDE
- details of the relationship between X and console
- details of the relationship between X and keyboards, mice
- details of the relationship between X and graphics card drivers and
monitors
- some of the on the ground guided tour material from XWindow-User-HOWTO but
with a perspective that promotes the user's ability to explore in their own
specific environment.
Lets call it the XWindow-In-Depth-HOWTO
Why is this needed? Take a look at any distribution's support mailing list
entries. What's the most frequent kind of problem? Is it related to X in
some way? I'd wager that it is. And I don't think its that people aren't
reading the howtos.
-Pat Callahan
P.S.
To take the tour guide metaphor a step further:
Quincy Market and Fanuiel Hall are two local sites on every Boston Tourist's
map.
We're not going to take you over to Quincy Market tell you all about it in
great detail and then point next door to Fanuiel Hall and say "Oh yeah
Fanuiel Hall is that building over there" Instead we're going to tell you
about them both, why they're important, how they're related, how to get
there and what to look at and what to ignore while you're there... Sound
good? Ok! Same thing for xdm, kdm, gdm, kwm, xwm, and anything else wm or dm.
This archive was generated by hypermail 2a24 : Wed Nov 21 2001 - 08:32:46 MST