Re: dia outline

[John Fleck <jfleck inkstain net>]

On Sun, Sep 03, 2000 at 07:52:39PM -0500, Kevin Breit wrote:

> Basically, I use the term "Concept based instead of UI
> based".  We used to go through each menu, say what it did, and let the user
> figure out how to put them together to actually work. For concept based, you 
> describe the tasks of the program, and how to do them. 

I think the new Dia outline is a terrific start in the right direction. But I
don't think it goes far enough.

It's hard for me to judge it without seeing in more detail how the
introductory "Quick Start" section will play out, but it seems as
though you have substituted the program's functional structure
(Canvas, Objects, Selecting Objects, etc.) for the UI's functional
structure (the way we used to do it) as an organizational principal 
for the doc. I agree that we need to move away from the UI. But I
think you need to take this one step further, and organize the doc, at
least an expanded version of the "Quick Start", in terms of the *task*
as the organizational principal.

So instead of:

QuickStart
 (brief description - "This section shows you how to get started
  using Dia to make ...".  This also shows off Dia's features
  and pretty screenshots.)
 +Creating a Canvas
 +Making a Diagram
 +Saving and Printing Your Diagram
 +Using Dia for Real-Life Applications

I would do something like:

QuickStart
 +Using Dia for Real-Life Applications
	+ set up a very concrete, very simple example of a job you'd use Dia to do
		+ define problem
		+ show screenshot of completed diagram
Then, use your example to step them through the following:
 +Creating a Canvas
 +Making a Diagram
 +Saving and Printing Your Diagram

Then, as you step through "The Canvas," "Objects," etc., you can
continually build on that concrete task. So, for example, when you
introduce gridlines, don't introduce it in terms of a feature of the
program. Introduce it with a task that needs to be handled, for which
the program feature "gridlines" is the solution.

You may end up mixing up the steps that are included in your current
outline, but that's OK, as the magic of indexing will, I hope, allow 
such a doc to serve as a complete reference as well as a functional 
guide. If you are concerned about completeness of documentation of 
the UI and all the program's features (I know this has been an issue 
for many on this list, and I do not disagreee), a terse appendix 
with a formal structure built around the UI or around program 
functions could suffice.

Cheers,
-- 
John Fleck
jfleck@inkstain.net (h)
jfleck@abqjournal.com (w)
http://www.inkstain.net/fleck/
http://www.abqjournal.com/scitech/