Re: PROPOSAL: UISG Menu Line Standardization

[JR Tipton <nails maybe net>]

On Fri, 7 Aug 1998, Bowie Poag wrote:
> This kind of stuff (user-end documentation) is a little difficult to
> mandate, simply because programmers dont really like writing
> documentation. :) Its very hard to set it into stone that ALL developers
> must include user dox with their apps upon releasing them, simply because
> a programmer's free time should preferably be spent coding, not writing
> dox. :)

Umm, no.

Try slicing out "programmers" and replacing it with "amateur,
unexperienced programmers." 

It is *not* difficult to mandate by any means.  Simply mandate it.
Amateur, sloppy programmers who have nobody working on documentation
including themselves will release amateur, shoddy applications anyway.

If, like you say, a coder's time is spent only writing code, then that
coder should get someone to architect the system as well as get someone to
write documentation (Fred Brooks).  Coders who pound out thousands of
lines of code without any sane documentation in the end are terrible warts
to the industry, plain and simple.  As a result, their applications will
be terrible warts to your GUI.

> I think most coders understand the need for documentation -- Its just very
> low on their list of priorities, and sometimes even non-existant on their
> list of "to do" 's..

If documentation is very low on their list of priorities, what does that
mean?  It means exactly what you might think it means: that anything and
everything but writing code is low on their list of priorities even though  
coding is, at best, 50% of the job of being a programmer ("Code 
Complete").

I suggest that at the very least a GNOME application must have concise,
helpful documentation accessable inside the program.

> Application documentation will likely be a requirement of Level 3 and
> higher apps. Look for a proposal like this to pop up mid next week.

Why?  This makes no sense to me.  Please, convince me that it makes
perfect sense to deliver an application to customers without verbose
documentation.

Lack of helpful, well written documentation has helped literally  
thousands of projects plummet straight into the gutter.  Disagree?  Remove
your man pages if you run a Unix derivative.  Remove the InfoViewer help
if you're a programmer under Win32.

Documentation must be required especially since the general reasoning on
this list is, "the user will have to conform to GNOME."

william r. tipton