Re: PROPOSAL: UISG Menu Line Standardization

[JR Tipton <nails maybe net>]

On Tue, 11 Aug 1998, George wrote:
> On Tue, Aug 11, 1998 at 02:05:09AM -0700, JR Tipton wrote:
> > 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.
> 
> actually gues what ... a lot of them did say JUST THAT .. and guess what ...
> there is plenty of documentation for their software ...

Huh?
 
> not force every user ... but the first person that gets fed up with not
> having docs will write them ... there there are docs ...

Okay.  So you're saying that the docs will get written anyway?  So what?
I'm not saying *who* has to write them, but I *am* saying that the
application should be delivered with them.  I say that when a person opens
an application that is GNOME compliant, there should be a verbose online
help because that would be consistent and helpful.

We could put everything else on the GUI style guide to "do it when you
feel like it" and see what happens.
 
> > Yep.  Exactly.  The developers should write the docs and that'd be the end
> > of it.
> 
> I don't see why really ... docs are written by whoever wants to writed
> docs ... rarely is the app so complicated that only the author can write
> any docs for it

I thought I explained this: if the docs are written from the beginning,
they will be better and the end user's experience will be better.  The
coders don't have to write it!  But the project lead should be dealing
with documentation, whether that means doing it herself or geting someone
else to (who wants to).  Simple, right?
 
> > I understand that documentation, when written, does not disappear.  We
> > agree on this point at least.
> 
> ok ... so go write a few docs ... if you feel they are so important ...

Like I said, I will be documenting my applications as I have done so in
the past.

> that's what people do in the free software world ... if something needs to
> be done they do it ... but only if they feel like it ... that's the whole
> point of it .... it works rather well actually ... people do a far better
> job when they want to do something as oposed to being forced into doing
> something ...

On this point I agree.  But there are certain things that need to be layed
down if World Domination is a goal.

Again, I'm not saying, "Make the people who don't like to write
documentation write documentation," I'm saying, "Make sure the
applications have documentation."
 
> GUI I write because I want there to be an easy way for people to use linux
> ... plus I enjoy writing gnome apps ... if I didn't I wouldn't be doing this
> in the first place ...

Hum hum... making an easy way for people to use Linux?  And if we don't
have documentation, then what?  Have 'em look at the code and start
writing their own docs.
 
> your ideas are the primary misconception most people have when coming from
> a commercial world into free software world ...

Right.  My idea that users need documentation is royally screwed up; my
"idea" that applications *should be delivered* with documentation is
pretty dumb, because hey! this is free software. In fact, no free software
needs documentation.  I'm not sure why I'm arguing this at all.

> in this world we are ALL users ... if we want tog et something done a couple
> of the users get together and write some code or documentation ... so there

Okay.  Then make sure they do it before you say your application is Gnome
Level X Compliant or whatever-the-hell-format they use.

> you  seem to be talking to me as if I were the software house .. and you
> are the user ... no ... we are both users ... if no users did figure
> anything out or didn't code their own little proggie ... there would be
> no linux ...

I understand this.  But if you've ever read esr's "Cathedral and the
Bazaar" you'll understand that there *is* in fact a project leader who
*does* do things other than code i.e. make decisions and hand out work.
If you're leading your own project, I say find someone who will write docs
for you and then you'll have nothing to worry about.  Easy enough.
 
> > 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:
> > See?  Simple.
> you  still seem to suffer this problem that new users will not have docs

Right.  If the style guide does not require concise online help at some
level then many applications will not have documentation.

> ... I'm saying they will ... trust me there are enough people familiar with
> the programs enough .. who will write docs ... for those new users ...

Eventually, yes.  Over time, yes.

Will these docs be outdated?  Yes, they generally are to some degree.  It
would be so much easier on everyone if they were documented from the
beginning of the release stages.  Can we agree on that at least?

> again ... we are all users ... everything is voluntary ... I can write all

Right.  And so is using a menubar.  And so is using buttons instead of
your own crazy wacky widgets.  But the style guide will enforce these
things.  Is that evil, wrong, anti-free software?  No.  It's in the best
interests of not only applications developers but the users as well.

> the software I want and not document it ...if I don't feel like it ...
> if you think it should be documented ... do figure it out and docuemnt it
> ... if you feel it should have such and such feature .. send me a patch ...

Then don't write the documentation, and don't be level Y compliant.
Nobody is forcing anyone to do anything, remember?
 
> no I'm not ... I wrote it on my free time ... the fact that I released it
> for use onto the masses is just my good will ... if they want docs .. some
> of them will have to write em ..

Look, you're still forgetting that even though there are many things about
free software that make it wipe up commercial software schemes it still
must adhere to certain expectations if it is to win the desktop.  You must
please the end user.

And yes, there will be many (as in, millions) of users who don't care to
write documentation for your Linux applications.  They would much rather
stick with Word for Windows because it has a talking paper clip.

Do you want to win the desktop?  If so, make sure that what is necessary
is done.  If not, <shrug> then don't.
 
> nothing is the "fault" of anybody ... it's NOT like in the commercial world
> where there is a company .. and the company makes a product .. well then
> the programmer is responsible for it I guess ... in the free software world
> .. there is no product ... there is some code that was written by somebody
> ... if others want to use it they can ... nobody's forcing them to ... if
> they feel it should have docs ... one of the users will write docs ...
> nobody is "responsible" for anything ...

Say again?
 
> > 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.
> 
> you must have taken one of those software engeneering classes in college ...

I've yet to have "one of those software engineering classes in college..."

I'm going to ask you a question: have you ever even read Fred Brooks?
Don't skirt it by snipping it out of your reply as others have done.

> hmmm ... again ... this is not a product ... this is something I do for fun
> ... if I feel like making it really complicated ... I can ... if I feel like
> not putting any docs in it ... I can ... 

Exactly.  If you feel like making it GNOME compliant, you can.

> > Ah yes.  More of this "free software defies the laws of nature" stuff. You
> ummm .... nobody said free software doesn't need documentation to be widely

I can't make sense of it!

> yup ... so go document a few apps ... in the meantime ... I'll be coding

I've got enough coding of my own to do.  But guess what?  Documentation is
part of that process.

Look, I think it's easy and fair enough: nobody says that the coder must
write the documentation, nobody is even saying that applications must have
documentation.  I'm just suggesting that applications that are Z level
compliant have documentation online and I assume that the development team
will take that responsability if they want to be level Z compliant... who
really does it makes no difference, as long as it is correct and concise.  
If  this is not required, GNOME will not beat Windows on the desktop.
Ever.

william r. tipton