A Modest Proposal for a New Guide

[Karsten Wade]

On Sun, 2006-11-12 at 20:19 +0530, Shayin C K wrote:
> I think it is a good idea. As soon as the 'Powers-that-be' approve it,
> we can have a go at it.

That was discussed; you all are the power here, the only delay is the
one where we make sure we are doing the right things the right way as we
proceed. :)

> My own suggestions and ideas:
> 1. The section on Getting Started begins with how it is similar
> to/different from Microsoft Windows. I think Fedora has matured to a
> point where we have to get rid of this Windows fixation where we have to
> point out how better or worse Linux is compared to Windows.

It should not be a better/worse but a comparison to what people
understand.  Since a flavor of Microsoft Windows has >75% of the desktop
market, and many people who use OSX also have used Windows, it has
become a common frame of reference.

That said, your point is a good one.  We want to watch for better/worse
and focus on compare/contrast where it is useful.

The story is simple -- one of the Microsoft tricks has been to take a
generic word or generic OS/desktop ideas and make them a trademark.
Take "Windows" and "Office" as two prime examples.  It therefore makes
it every hard to have a discussion about a desktop without either
referring directly to a comparison from MS Windows, or having to use
longer work around sentences to make it generic:

"OpenOffice.org has matching functionality to Microsoft Office, with the
ability to read and write from MS Office files, as well as support for
the standard Open Document Format (ODF).:

v.

"OpenOffice.org is a productivity suite with tools that are useful to
people using a desktop for doing standard office work.  It includes a
full-featured word processor, spreadsheet, and presentation software, as
well as support for ODF ..."

Which is a nice segue to your point below[1].

> 2. The Desktop user guide reads: "After reading this, you
> _should_(emphasis mine) be able to ..." Suppose a user is not able to
> all that? Is he supposed to feel bad about it?
> I think our style should be more non-judgmental and without laying any
> targets for the user. Let us not set any objectives for the user. Let
> him get started. Let us not intimidate him.

+1 Agreed about judgmental language.  However, this is an interesting
idiomatic situation.  The word "should" is used here because things may
not be exactly the same for the user; the should is way of saying, it is
OK if things are not exactly the same.  But because of the multiple
meanings of that word in the sentence, it sounds as if a test is being
applied -- you should be able to do this, and if you cannot, you are
stupid.

Wording might be better as:

"This guide shows  ...

* How to log in to your computer
* What is on the desktop
..."

[1] Segue from above ...

> 3. The number of technical sounding words can be brought down or at
> least they can be suitably hyperlinked(another technical word ;-) ). For
> example(fedora Desktop guide):The technical words:
> login, layout, default, desktop, file, navigator, e-mail 'client',
> web-browser, office suite, customize
> Let us assume that a new user who has never used any
> computer(Windows/non-windows) starts using Fedora Core and we have to
> manage to get him working. Why do we assume that only a technically
> experienced user will be switching to Linux?

This is just my opinion here, so if the majority of the project wants to
get into the business of teaching computer use from scratch, we can do
that, but I do not think we should.

We have to start from some base.  If our base is always to teach users
what a mouse is and how to use it, then we are:

i. Reinventing documentation that exists in the thousands already;
ii. Using time to teach basic skills rather than how to use those skills
in Fedora;
iii. Writing content that is not specific or unique to this Fedora.

What I suggest is this:

1. Write up a brand new guide "What is a desktop and how do I use
one" (or something like that);
2. Pair that guide with a glossary[2] that has:
   i. Links to other glossaries so we don't have to spend our time
maintaining a document of "What does login mean"
   ii. Provides definitions for terms unique to Fedora, Linux, and FLOSS
3. Have the new "What is a desktop" guide linked from the intro for all
guides that are for new/beginning users.

Then we can have all guides say, "You need to know the material covered
in X, Y, and Z."  X, Y, and Z are then a set of guides that provide a
base of common understanding that we can rely upon for the rest of the
guide.

Does this make sense?

- Karsten
[2] http://fedora.redhat.com/docs/jargon-buster/ and it needs updating
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20061113/59f2632d/attachment.sig>