Re: PROPOSAL: UISG Menu Line Standardization

[Peter Bortas <peter idonex se>]

JR Tipton <nails@maybe.net> writes:

> 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?

Because by following the guide the programmer decreases the amount of
documentation he has to write to get people to understand it. Besides,
it's fun to fool around with GUI-widgets and other user interaction
thingies. Writing documentation is not.

> 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.

I dare you to find an Oracle employee that wants to write docs on his
spare time.

> > 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?  

Of course. It's quite simple. GNOME is going to suffer in two ways:
1. Programmer will not make the effort of making their programs Gnome
   compatible since the first thing they have to do is write doc.
2. Other programmers will make nice manual containing only the word
   "UTSL" to get it Gnome compatible. That entry could have been
   something useful instead, like a general guide to using GNOME
   applications as earlier suggested.

Therefore documentation should NOT be in GC1. Don't get me
wrong. Documentation is vital, and programmers know that, but Gnome
will only suffer from making doc GC1.

-- 
Peter Bortas                   http://peter.bortas.org
Idonex AB                      http://www.idonex.com