Re: Style Issues for 2.0

[Dan Mueth <d-mueth uchicago edu>]

On Wed, 14 Jun 2000, Aaron Weber wrote:

[snip]

> That would move the docs we have and continue to maintain more towards
> a task-based guide, rather than a UI-based reference.  

I feel this would be a great improvement to our documentation
style.  Right now, we are writing more of a reference guide with the
emphasis on describing what each menu item and button is for.  This is not
fun for a user to read, and most of it is obvious (like what the "cut" and
"paste" and "undo" and "exit" and ... buttons do.) Further, when we have
context sensitive help (ie. popup help) which will allow a user to
actually select any part of the UI and get a short pop-up message
describing that button or object, this style of writing will be further
obsoleted.  For now, I suggest we at least take emphasis off the UI
description by moving these sections back in the documents.

If we agree on this point, the next question is what we should be doing
instead.  As I see it, there are two extremes we could do.  One is to do
completely task oriented documentation - each section is labelled "How to
..." and the section concisely tells the user how to do a certain thing
with the application.  The advantage of this is it is easier for a user to
find the information, read it quickly, and get back to work.  Note this
requires really good indexing, which we must have for GNOME 2.0, as well
as a basic level of user competency.  The other style is that we would
write *readable* documents which a person could sit down and start reading
from the beginning of the document and which creates a complete picture of
the application, what it is able to do, and how to do things. Here I
divide the users into two extreme categories - A) the semi-competent user
(say a person who has used Macs or Windows for a year or two) who gets the
main ideas of the application, and just needs some help on details, and
who wants to learn how to do a specific task ASAP and get back to work,
and B) the person who likes to sit down and read about an application to
learn how to use it.  Note that in neither case do we want to tailor to a
person who has never seen a computer in his/her life - we may want an
introductory document for super-newbies (as Aaron discusses below) - I
think we should assume a competency level of at least basic familiarity
with Windows or Mac.

I propose we find a middle-ground between (A) and (B), leaning towards
(A).  Most people have a basic familiarity with UI's and most people do
not want to sit down and read a full article/book to learn how to use each
application.  Perhaps we can start with a nice descriptive
introduction/overview which describes the basic features of the
application, then move into a slightly task-oriented style of writing so
that people can find the information they are looking for quickly. We can
leave the detailed UI description to the end or maybe eventually remove it
after the context-sensitive help is implemented.

[SNIP]

> c) the little "New to Linux? Switching from Win? from Mac?" sort of
> section we've been bandying about lately.

I like this idea.  We should put some general information in here for
newbies, and pull it all out of the application manuals.

If we have the manpower, perhaps we can venture even further into what
Dave and Kevin have suggested - having a document on basic system
information (part GNOME/part OS).  This could explain things like setting
up sound, X, modems, etc. - clearly this would depend strongly on the OS
and distribution, so we would need multiple copies customized for each
system.  It seems like this is what most users really need - a new
RH/GNOME user should be directed to a brief chapter explaining rp3, not
the PPP-HOWTO. This is a very nice idea, although it would be *a lot* of
work. I don't think this is the highest priority for the GDP, but if any
author would like to work on this, I don't see any problems with it.

> So, that's basically: 
> a) everybody knows we need an index
> b) what do you all think about moving to more task-based documentation,
> with the caveat that we add other things to take up the slack
> c) would it be ok for me to do some more work on the GDP handbook, to
> put in a style guide, and if so, what do you think should go in it?

I think these are all great ideas.

Dan