Re: Dia quickstart

[Dan Mueth <d-mueth uchicago edu>]

On Sat, 23 Sep 2000, Kevin Breit wrote:

> Oh so faithful doc writers,
> 	I just finished up writing the first draft of the Quickstart section for
> the Dia manual.  If you can, would you please go in there and say goods and
> bads?  I'm not really looking for "Your spelling is off" type of thing.  I'm
> looking for criticism on the Quickstart setup that I employed.
> http://www.datasurge.net/~battery841/dia-manual/quickstart.html
> Kevin

Kevin,

This looks like a great start.  Since I like the overall layout, I'll
suggest some smaller comments/suggestions like you said you didn't want ;)

1) I would move the explanation in the Introduction about how to start Dia
into the QuickStart.

2) I would try to mix concepts and instructions a bit more.
For example:
"To create a new canvas, you just go into the File menubar, and hit the
New diagram button. A new canvas will appear on your screen. That's all
there is to it, honestly. "
->
"Each diagram is drawn onto a separate <i>canvas</i>.  To create a new
canvas, select File->New Diagram. A new canvas window will appear."
(proper markup omitted here)

This both saves some space and combines the GUI oriented instructions
with the basic introduction of terminology and concepts.  The "File->New
Diagram" notation, which is great notation IMO and makes things flow nice,
is produced with:
   <menuchoice>
    <guimenu>File</guimenu>
    <guimenuitem>New Diagram</guimenuitem>
   </menuchoice>
You can also insert <guisubmenu>'s in there if appropriate.
When introducing a new term like "canvas", use of <emphasis> seems
appropriate.

3) The "Making A Diagram" section is really the main part.  You can
probably make it a little bit longer to discuss the types of objects
available and point out any fancy/non-obvious features or actions:
a) select pointer and double-click on an item to edit its properties
b) brief description (one sentence) of layers
c) transparency
d) (anything else?)

4) In the section "Who Does Dia Appeal To?", you might consider using a
list with formalpara's to list all of the various applications for
Dia.  This makes it much easier for a person who to read/skim through.

5) Looking at the "Saving and Printing Your Diagram" section, I would
suggest targeting your audience a little higher.  Consider your audience
somebody who has run a few GUI programs before - probably Word and Excel.
For this audience, they know all too well they have to save their programs
often in case it crashes ;)  I think you can compress the 4 sentences
about saving into one, considering a higher audience level.  What is
missing here and of importance to a new user is a discussion of what
formats Dia can export.

I hope these suggestions help.  They are all small picky points, but
that's all I could come up with.  Looks like it is coming along really
well.  

Dan