Re: Screenshots in Gnumeric Docs.

[Eric Baudais <baudais okstate edu>]

I think that all this is very good to see.  Planning for the docs in a sane 
manner is will make everything easier.  Yet right now the main push of the 
GDP, imho, is to get the XML format working throughout the help system and to 
correctly implement the API Mr. Blandford has made.

On Thu, Mar 14, 2002 at 05:37:32PM -0500, Jody Goldberg wrote:
> On Thu, Mar 14, 2002 at 04:37:33PM -0600, Kevin Breit wrote:
> > 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.
> As Scott points out there is a usecase for element docs.  Specificly
> finding an explanation of what some feature actually does.

I think this will require context sensitive help.  For some reason people keep 
saying this has to implemented in GTK+.  Since it wasn't implemented in 
GTK+-2.0 like it was supposed to hopefully this will happen in the next major 
release.

> > Adrian asked the following requests:
> > 1) Who the help (or sections) are geared towards
> Gnumeric like most office apps is going to have 2 broad user groups.
>     - your average user that just wants to get some work done.
>       These folk need 'howto' type writups for day to day
>       operations.  1.0 is sufficient for the majority of there
>       needs.
>     - power users
>       This is a whole different ball of wax.  1.0 is no where near
>       complete enough to handle the extras these folk want.
>       Additionally what they want is ulta-detailed specs of what
>       each feature does.  Something only marginally higher level
>       than reading the source.
>
> Catering to the former seems like a higher priority right now
> because that set of capabilities are not going to be changing that
> quickly.  Trying to document the power features as they are being
> implemented seems like an excercise in frustration.  Those docs will
> likely be generated as the features firm up.

I would also like to add 2 other groups.
    -your average user coming from MS Excel.
         These folks will know the basics of how a spreadsheet works. They will 
         know how Excel does things and will want to know what has changed from 
         their traditional way of doing things.  It should point out the changes 
         and also why the change has occured, possibly pointing how some new 
         features.

        -your new user to spreadsheets.
         These people don't know much about the general layout of the spreadsheet 
         or even how to operate one.  They just know they need a pie chart or a 
         line graph of some data and maybe some formulas in the sheet.

> > 2) What the outline of the help structure is to be
> > TOC
> automated I hope
> > Introduction
> optional
> > Task Description
> useful
> > Glossary (optional)
> optional
> > Index (optional)
> NOT optional,  A good quality index is paramount.
> Very few people want to read an manual.  They want to be able to
> jump to the section they are interested in.

The long term goal is to have this automated so when the documentor wants to 
put a term in the index they add an indexterm tag.  I'm not sure the current 
state of this feature.  Maybe someone else can comment on it.

> > 3) A clear long term (several year) committment to a particular set of
> > formats. 
> I don't follow what you mean.

I'm not sure what you mean either.  The GDP has several long term commitments 
to particular formats.  Last year we decided to switch to DocBook XML and use 
XSLT to process the documents.  We're committed to using OMF for document 
meta data and having that meta data processed by scrollkeeper.  We hope that 
all application's documentation will take advantage of the infrastructure 
we've built or are in the process of implementing.

Eric Baudais