[Users] RE: Avpops tutorial - documentation

[G.Jacobsen]

Douglas,

> > Are you suggesting I learn C and look at the code?

Why not ? I looked the whole of last week through the source code and learnt
a lot.

If you have ever written a larger piece of software then you would know that
for programmers every functionality is obvious - while for the users nothing
is obvious.

Writing good documentation is almost as time consuming as writing the
software. I suppose that Bogdan and colleagues need also to make money
rather than write extensive documentation.

In any case, I think they are doing a great job supporting this project.

Perhaps some simple things which wouldnt incurr an additional burden on the
developers could help.

1. The whole documentation on openser could be in wiki format so users can
add their wisdom to every function as they stumple across it. To start with
one could duplicate the existing module documentation pages as wiki so that
everyone can add his comments. And I would also make such new wiki pages the
default entry point for the documentation rather than the existing module
documentation itself. That way everyone would be reminded to add his wisdom.

2. ALL functions and keywords of all modules could also be accessable on ONE
page (possibly by extending the cookbook) which then links to the wikis for
the modules. I often find myself hunting through several module docs,
websites and search engines to find insight into a function.

Cheers

Gerry




-----Original Message-----
From: users-bounces at openser.org [mailto:users-bounces at openser.org]On
Behalf Of Douglas Garstang
Sent: Montag, 5. Juni 2006 21:02
To: greg at thursday.com
Cc: users at openser.org
Subject: [Bulk] RE: [Users] Avpops tutorial


The documentation is not very good.
It's a wee bit difficult for others to write documentation when they can't
figure the software out, because the developers never wrote any good ones.
Eight months of openser and I'm still trying to work out how all this branch
stuff works. Don't have a clue, and there's no books on this stuff either.
If you ask in the list you get half answers and riddles.

> -----Original Message-----
> From: Greg Fausak [mailto:lgfausak at gmail.com]
> Sent: Monday, June 05, 2006 9:23 AM
> To: Douglas Garstang
> Cc: Juha Heinanen; users at openser.org
> Subject: Re: [Users] Avpops tutorial
>
>
> Douglas,
>
> The programmer did write documentation!  That's what we
> currently have.  Often it is a good idea for a non-programmer
> (ie. user)
> to write the documentation from their point of view.
>
> Anyway, this is open software and the more people that help
> develop it (and it's documentation) the better.  If you don't write
> it I'm sure somebody will someday :-)
>
>
> -g
>
>
> On 6/5/06, Douglas Garstang <dgarstang at oneeighty.com> wrote:
> > > -----Original Message-----
> > > From: Juha Heinanen [mailto:jh at tutpro.com]
> > > Sent: Sunday, June 04, 2006 11:01 AM
> > > To: Douglas Garstang
> > > Cc: Bogdan-Andrei Iancu; Sam Lee; users at openser.org
> > > Subject: RE: [Users] Avpops tutorial
> > >
> > >
> > > Douglas Garstang writes:
> > >
> > >  > I'm not one of the developers.
> > >
> > > you don't need to be.  in fact, it would give developers'
> more time to
> > > develop, i.e., write code.
> >
> > How can I write the documentation when I don't understand
> how the software works?
> > Are you suggesting I learn C and look at the code?
> >
> > I'm of the opinion that developers should write
> documentation. If other people try to do it, they make bad
> assumptions based on what they THINK they know. They then
> write bad or wrong documentation which others read, and in
> turn also write bad documentation. It's not a good model.
> >
> > Doug
> >
> >
> >
> >
> > _______________________________________________
> > Users mailing list
> > Users at openser.org
> > http://openser.org/cgi-bin/mailman/listinfo/users
> >
>
>
> --
> Greg Fausak
> greg at thursday.com
>

_______________________________________________
Users mailing list
Users at openser.org
http://openser.org/cgi-bin/mailman/listinfo/users


		
___________________________________________________________ 
Try the all-new Yahoo! Mail. "The New Version is radically easier to use" – The Wall Street Journal 
http://uk.docs.yahoo.com/nowyoucan.html