Re: PROPOSAL: UISG Menu Line Standardization

[JR Tipton <nails maybe net>]

On Tue, 11 Aug 1998, George wrote:
> what I said is that you CAN'T force people to do anything .. people writing
> a free project will do whatever they want ...

I'm not suggesting that anyone put a gun to someone's head.  I am
suggesting that if a development team wants its application to be GNOME
compliant, then it writes documentation along with the whole slew of other
things it'll have to do.

Easy, right?  Right.
 
> now if a company like redhat decides that what gnome needs is good docs ..
> hires a couple of doc writers and write 20 books about it ... hey good for
> them ... that's the way it works ... that's the way it WILL works .. and
> that's the way it has allways worked

I'm not sure what you're saying here.  Please clarify.

> > If I want to know how to spell a word, I look it up; I don't write my own
> > personal dictionary by frantically searching every paper I can find that
> no I run ispell ... that's what I've always done .. and to the best of my
> knowledge that's what just about every unix weenie I know does ...

You missed the point.  I didn't mean it in the literal sense.
(Are you sure you run ispell?)

> > If I want to know how to fix a part on my car, I look it up; I don't try
> > everything possible until something *seems* like it works... which is
> > exactly what stereotypical Unix weenies have done forever.
> 
> yes ... so ... if I want some info on how to do something ... I'll look it
> up ... man -k ... whatever ... I search the web ... if I can't find anything
> on it .. I will still try ... if I feel like this should be better
> documented I write the doc and send it to the author ... 

You *look for documentation* first!  What if there were no man pages
because everyone thought, "gee if you want man pages then write 'em on yer
own pal"?  You'd be screwed, that's what.

If the docs aren't there?  The answer, to you, is obvious: force the
user to figure it out on his/her own.  If that makes sense to you, I think
something is fundamentally wrong with the way you view software.
 
> > wouldn't purchase another thing from them.  If GNOME applications come
> > deliviered with a note that says, "figure it out," I'll be the first (of 
> > thousands) to choose the commercial world.
> 
> no ... BUT .. you don't seem to understand ... the docs only have to be
> written once ... then they are there aren't they?

Yep.  Exactly.  The developers should write the docs and that'd be the end
of it.

I understand that documentation, when written, does not disappear.  We
agree on this point at least.

> > Write the documentation.  The users will love you for it.
> yup .. they just might ... do I care ... maybe ... does this force me to
> write anything .. no ... will I write docs ... I just might ...

If you don't care what the user's experience is, I'm not sure why you're
on this mailing list.  Can you give me some insight as to what your
position is on the user's experience?  Why even have a GUI?  Screw the
user, right?  Let him make his own GUI while he's writing his own docs.
Hell, let him build his own computer out of gum wrappers: it's not
anyone's job to do anything because doing stuff sucks!
 
> what I'm saying is that .. I might not write docs .. I might write a few
> crappy lines about the program ... 
> 
> but I'm pretty sure there are people around that WANT docs for gnome ...
> and they will write those docs ...

No!  You've got it all wrong!  The people who *want* the docs are the
people who *can't* write the docs!  It's very simple, really:

a) Developers know the program well.
b) New users do not.
c) Users will want documentation.
d) Following c, documentation must be written.
e) Following a and b, developers would be the best to do it.

See?  Simple.
 
> if you want gnome to have docs ... do your part ... write the docs ...

Okay, I promise to document my applications: in part because I care about
the user and in part because I have a sense of professionalism.
 
> whining about no docs or ANY OTHER aspect of free software just makes you
> look dumb ... you didn't buy this software ... nobody is "responsible" for

Wrong.  The application developers are responsible for every aspect of the
code, plain and simple.  If their software has no documentation, then it
suffers and it is the fault of the developers.

Who is whining, anyway?  I'm not whining, I'm telling you like it is.  If
you don't know enough about software development to have a decent
understanding of how crucial documentation is to the whole process is...
well, then, that's a different story.

> making you feel cozy with it ... if you think something needs to be done
> the only thing to do ... is to do that thing ... saying "it needs to be
> done" ... just won't get you anywhere ... wheather that thing is fixing
> bugs writing docs ... or whatever else you think up ... you can't FORCE
> anyone to do it ... and whining about it not being done doesn't help ...
> doing it does ... but again ... this is free software .. if you don't feel
> like doing it ... don't ... 

Ah yes.  More of this "free software defies the laws of nature" stuff. You
start with saying that free software doesn't need documentation because
it's free.  Next you'll tell me that free software code doesn't need
comments just because it's free.  Then you'll say that it doesn't *really*
need to compile because hey!, it's free.  Then you'll tack on: just think
it up and tell everyone about it because hey!, ideas are free.

Documentation is a requirement for World Domination.  If GNOME wants to
thrust its way onto desktops, documentation is a part of that.  Take it or
leave it.

william r. tipton