Re: reduce redundancy?

[Kenny Graunke <kwg teleport com>]

On Sat, Aug 19, 2000 at 10:44:12PM -0500 or thereabouts, Dan Mueth wrote:
> On Sat, 19 Aug 2000, Kevin Breit wrote:
> > Hey guys,
> > 	I was curious if we'd be willing to save ourselves time!  Oh yeah we
> > all do.  So now how to do that.  I figure we could put a template for some
> > commonly used sections or what not.  For example, 90% of Gnome apps have a
> > File/New
> > File/Open
> > File/Save
> > File/Save As
> > File/Quit
> > Why don't we create a publically available text file, not even SGML, that we can
> > use for other docs.  The other advantage to this, is that we'll know that all
> > the docs have the same definition for Open or what not.  I just figure that
> > it may take me 10 or 20 minutes to do a File menu, when it can, and should be
> > spent doing other stuff.  I figure a simple template with all this stuff in
> > it can save us all...just a little bit of time and redundancy
> 
> Do we all agree that we need to document all of the menus, even the
> somewhat obvious ones like the ones Kevin lists above?  I get the idea
> most people agree on this, but I just want to be sure.  (Speak now or
> forever...)

OK, I'll speak now. :-)

All non-app specific GUI elements should go into a new global doc. This new doc
would cover things like basic menus & menu items (File->Open, Edit->Copy, Cut,
Paste, and so on). It would be geared for people new to the computer, as most
computer users would most likely already know these basic elements.

Putting the same common elements in every doc forces the readers to sift
through the boilerplate to try and find the actual information they're looking
for. I don't think that automating the repetitiveness is a good plan; I'd
rather eliminate the repetitiveness in the first place.

I am not suggesting providing a link to appropriate section in the global doc
for all GUI elements. If you do that, you might as well include the text...
I would say that linking provides most of the the disadvantages - most of our
sections are fairly small, linking to them would keep the same material in the
doc, yet make it so you cannot simply print a page with the info.

The global doc could include this, but evolve into more of a guide for new
computer users. I remember that the mac had a tutorial for new computer users,
and it was very good. A doc serving as an introduction could be useful.

[snip!]

> Sasha's idea of linking to other docs which explain certain concepts is a
> good one.  I think it would work well for his example (tearing off menus),
> but for Kevin's particular concern (particular menu items which are
> commonly used), I think the entity or reference doc would be better
> suited.

I consider things like tearing off menus to have no place whatsoever in app
docs, not even linking. Common menu items could arguably have their place,
but really are best left out. See above for my proposal.

Kenny