Re: dia outline

[Dan Mueth <d-mueth uchicago edu>]

On Sun, 3 Sep 2000, Eric Baudais wrote:

> Malcolm-
> 
> Welcome to the GDP.
> 
> On Mon, Sep 04, 2000 at 11:40:37AM +1100, Malcolm Tredinnick wrote:
> > Probably time to decloak on this list and contribute something...
> > 
> > I have two questions about this outline:
> > 
> > (1) A lot of it if pretty specific to the particular way that Dia works, isn't
> > it? I'm wondering which parts you see as being part of the template. I like the
> > idea of having a flow of instructions that let the beginner get started
> > immediately and let the more advanced person learn everything they want to about
> > specific components. That is certainly a model to preserve in a template. Are
> > there other "common" portions that I've overlooked?
> 
> The changes I see is the elmination of a menu reference section, which
> I think is needed without context sensitive help.  All the sections
> are divided up into specific topics related to Dia.  The templates
> have the section organized according to the User Interface (UI).  You
> pointed out the quick start guide.  I really like this as the
> beginner, who wants to get a feel for Dia and not read the whole
> manual can start immediately.  Sometimes this isn't needed, like in
> games, but other times the program isn't as intuitive, as in Dia's
> case.

Yes.  Kevin and I talked for quite a while about the Quick Start section,
and I should probably write down some of our thoughts here.  First, as
Eric says, not all applications need a Quick Start.  Complex or big
applications probably should have them though.  The Quick Start section
can be used to do a few things, and which they do/emphasize depends on the
application and the opinions of the author.  These include:

1) Explain how a user can get started using a complicated/tricky
application.

2) Show off the capabilities/features of a program. (ie. sort of marketing
the app) Show what it can do (and what it can't do). Show some cool
screenshots to attract people's attention.

3) Show how an application could be used in real life.  Dia is a good
example of this.  It is a fun application, but who uses it and what
for?  Can your average GNOME user use it for anything practical?  What?

ie. If a person is looking at the doc, either they want to figure out how
to use it or they are trying to figure out what it does and whether they
should use it.

For most applications, excepting a few basic applications everyone users
like a web browser and word processor, a user starts off not really
understanding what the application does or how to use it. They are willing
to spend about 1 or 2 minutes skimming over the Introduction and the Quick
Start section.  If they don't understand the basics of what it does or at
least see some cool screenshots after a couple minutes, they are not
likely to dive in and read the next 4 chapters to figure it out.  This
applies to applications like Dia, while it may not apply to FreeCell or
Mozilla.  So whether there is a QuickStart and how it should be tailored
depends upon the particular application.


> > (2) I know there have been discussions on here before about how
> > self-contained each manual should be, but I wasn't sure what
> > definite conclusions were arrived  at. In this particular instance, I
> > have in mind the printing section:
> > > Printing 
> > >  +Page Setup
> > >  +Selecting A Printer
> 
> There have been no definite conclusions yet, just a bunch of ideas.  
> I would like to see a generic printing help in the dialog.  So, when
> you press the help button on the print dialog a generic help pops up.  

Yes.  This is on our TODO list.

> But there are instances when there are more options than what the
> standard gnome-print dialog contains.  In these instances I would like
> to see a printing section in the manual to explain the specific
> printing options to Dia.

Yes.  In cases where the printing dialogs are standard, we may want to
include them as entities.  This gives the user the option of seeing them
and printing them out as a complete doc if they want to.

> I do not think that all of these generic help bits should be compiled
> into a new users guide, as you imply.  They will be very accessible
> via searching in Nautilus.  So, if you want to learn about printing,
> you should be able to type printing and be able to find the generic
> printing dialog help quickly.
> 
> I do not have any ideas about implementing these generic help bits for
> the same dialogs in GNOME apps.

Good point.  Does the "Help" button in Dia's Page Setup dialog technically
have to point to the same URL as the "Help" button in Gnumeric?

Dan