Screenshots in Gnumeric Docs.

Hey guys,
        Below is both an email I sent Adrian and an email he sent to me.  I
added gnome-doc-list to the Cc: list, thus the reiteration.  If you've
read this before, apologies.

On Thu, 2002-03-14 at 20:10, Adrian Custer wrote:
hey all, 

this is in response to Kevin's message to me. 

On Thu, 2002-03-14 at 16:40, Kevin Breit wrote: 
    Okay, currently Gnumeric has upwards of 200 (or was it 300) figures. 
We don't need that many.  I honestly think that having a screenshot of a
box with the caption saying "This is a box" does nothing but take up
time and space on the page.
    I am proposing we drastically cut down the number of screenshots we use
(limit to like...maybe 30, tops).  I would like you to go through the
figures and delete the stupid ones.
    Now, how do you know what is stupid?  Screenshots should be a visual
reference to a user interface.  If you have any questions about what to
do or if a screenshot is "stupid" then don't hesitate to ask.
    This doesn't need to be started for at least a couple weeks, if not
months.  Would you be able to do this?

When I picked up the documentation, they had an exhaustive list of the
gui-elements that was woefully out of date. One of the early docs in the
gnome doc project said that all gnome project docs should have an
exhaustive list of the gui-elements. However, 
1) there was a strong push for a totally different approach that
involved "task based" explanations as opposed to "element based"
2) lots of pictures don't do much for most people. 

Part of our problem is we are all targeting different audiences, with
totally different requirements and the current vision of a help system,
a linear document, is not nearly flexible enough. 

My ideal vision is the following. It requires a different infrastructure
and therefore is way beyond my capabilities. Clicking on "help" should
bring up a page something like: 

**             Welcome to Gnumeric Help                          *** 

1) Basic Intro 
2) Exhaustive list of Gui Elements 
3) How-To's 
4) Search 
5) ...others? 

This could be tabs, or links or any structure. Both windows and macos
allow users some of this flexibility. Sometimes we want to know what a
button does, sometimes we want to know how to do something. How to find
what we want is not a linear process. 

I don't have time to follow the gnome-docs discussion so I don't know at
all what the structure is for gnome 2.0. Because I don't have time, I 
will leave the decisions to others. I'll be glad to contribute as long
as we have a well articulated vision for the long term. This should be a
two or three paragraph statement which includes: 
1) Who the help (or sections) are geared towards 
2) What the outline of the help structure is to be 
3) A clear long term (several year) committment to a particular set of

Kevin, I know you wrote up a white paper earlier on this last part so
this could simply be "3) is that doc." 

I am not trying to flame or insult anyone so my strong statements are
not intented to be negative. Docs can be really difficult. In a couple
of weeks, I'll drag in a friend who does docs for a living and see what
he can suggest. 


I understand the purpose of having a GUI element reference.  I don't
really think that they are a huge benefit to most users.  I can't recall
the last time I said "What does this button do!?"  If I do question, you
have tooltips for the job.  A GUI reference is used less than the real
documentation and would be a huge task for the documentation writers. 
If a user wants to write it, they can.  But I question if it really is
OVERLY important.

Adrian asked the following requests:
1) Who the help (or sections) are geared towards

The help should be geared towards end users.  Each application is going
to have different end users.  Glade is going to be development based,
thus should have a lot higher technical level.  My Third Program though,
should be geared toward children.

2) What the outline of the help structure is to be

Task Description
Glossary (optional)
Index (optional)

3) A clear long term (several year) committment to a particular set of

Is this SERIOUSLY what we want?  We all know stuff on the internet
changes really quickly.  Binding ourself to a several year commitment
may make us have our 'thumbs-up-our-asses' (pardon the language). 
Anyways, formatting and such like that should be left up to the doc
writers, not a whole group.

Comments please?


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]