Re: PROPOSAL: UISG Menu Line Standardization

[JR Tipton <nails maybe net>]

On Sun, 9 Aug 1998, Bowie Poag wrote:
> > Preben Randhol <randhol@dusken4.samfundet.ntnu.no> writes:
> > No. It is not rubbish. As a programmer I can tell you that
> > documentation is a long way down the priority list when I do hacks on
> > my free time. GDK is not overly documented, but on the other hand I
> > doubt there would be a GDK if there had been someone demanding
> > documentation from the start. Programmers don't take wery well to
> > orders.

If programmers don't take very well to orders, why write a style guide
with requirements in the first place?

I would say that if GDK was ignored because of its lack of documentation
you would see a better API out there.  Look at 3Dfx's Glide, for example:
well written, verbosely documented.  Nobody complains about the
documentation; in fact, that's why so many programmers use it!
 
> Thank you. :) I've been working with programmers on one or more projects
> since like '92, and it never fails -- The LAST thing that ANY of them
> wants to do, is document. 

So what? 

Since like '92?  Which kind of programmers have you been working with?
Nevermind, I needn't ask: amatuer ones.  Sure, they may be able to sling
thousands of lines of code, but they're not professionals.

I dare you to walk into Oracle or some place of the like and say, "hey man
I just like to write code, documentation sucks."  You know what kind of
reply you'll get.

> They feel whatever you have to write for command
> line help should be sufficient.

Does this make it right?  When the heck was the last time a man page
helped any normal, average user out?

I would also propose that there are coders out there who feel it
sufficient that their application only crashes 75% of the time.  Does that
make it right?

> Coders are coders, thats never going to
> change. You can only encouraget them to write the documentation in order
> for their program to gain more acceptance in the public.  You cant force
> them, ala a Style Guide requirement, to write dox -- They'll reject it
> outright.

You're wrong on this one, Bowie.  You *can* force the programmer to write
documentation.  It happens all day and all night in this industry: look at
any software review in any magazine of a product that had shoddy
documentation and you will see that lack of documentation is spit at. 

And I'll bet my rear that it's the right thing to do (requiring
documentation).

If a coder is so flat out ignorant and anti-user from the beginning, I
have two questions:
1) Why is that coder coding anyway?
2) Why doesn't the coder get someone to write documentation?

Since you seem to have the realization that coders aren't the best in the
world at communicating things to users, explain to me how you believe they
will communicate an interface so well that it does not need documentation.

I challenge you to prove that GNOME would be worse for requiring
respectable documentation.  That's what this is about, right?  

william r. tipton