Re: Return of the Template Revisions, part MDMXCII

[Eric Baudais <baudais okstate edu>]

Aaron Weber wrote:
> 
> Hey all--
> I've posted an sgml file of my stab at template revisions at
> http://primates.helixcode.com/~aaron/gdp.html
> and eagerly await your flames, er, constructive criticism.
> 
> It's significantly different in a couple ways: MY-GNOME-APP has
> increased its functionality, so I broke the main window section into two
> <sect3's>.

I like how this aims at providing a guide to complete certain tasks
using the application.  It is one of the goals of the documentation, to
provide the reader with instructions on how to do things/use the
application.
 
> I also ditched the menubar section, and i'm unsure about that-- it did
> provide some information, but not all of it really necessary.  See what
> you think!

I don't like this at all.  I think the other goal of user documentation
is to provide a reference to the application itself.  I think the
menubar does this in a nice and complete way.  I would also like to see
a section for the toolbar, much like the menu bar, to provide a
reference so people can obtain quick help on a menuitem they are unsure
about its use.
 
> I haven't checked this into CVS because it's not ready for CVS yet, but
> if response is good, I'll polish it on up and commit it.
> If response is bad, I'll fix it up and then commit. ;>

I would also add a section for a FAQ before the Known Bugs and
Limitations section.  This is another possible way to provide a quick
answer guide for  the application, if one is written.

I like the template, but would add the above mentioned items too it.
Keep up the good work, Aaron. :)

Eric Baudais