Screenshots in Gnumeric Docs.

[Kevin Breit <mrproper ximian com>]

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: 
> > ac,
> > 	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?
> > 
> > Kevin
> 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"
> explanations. 
> 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
> formats. 
> 
> 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. 
> 
> cheers, 
> adrian

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

TOC
Introduction
Task Description
Glossary (optional)
Index (optional)

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

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?

Kevin