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@gmail.com] Sent: Monday, June 05, 2006 9:23 AM To: Douglas Garstang Cc: Juha Heinanen; users@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@oneeighty.com wrote:
-----Original Message----- From: Juha Heinanen [mailto:jh@tutpro.com] Sent: Sunday, June 04, 2006 11:01 AM To: Douglas Garstang Cc: Bogdan-Andrei Iancu; Sam Lee; users@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@openser.org http://openser.org/cgi-bin/mailman/listinfo/users
-- Greg Fausak greg@thursday.com
Douglas Garstang writes:
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.
i don't like your attitude. if you don't consider quality of openser or its documentation good enough and are not willing to do anything about it, i suggest you look for some other open source product or go for commercial offerings.
-- juha
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@openser.org [mailto:users-bounces@openser.org]On Behalf Of Douglas Garstang Sent: Montag, 5. Juni 2006 21:02 To: greg@thursday.com Cc: users@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@gmail.com] Sent: Monday, June 05, 2006 9:23 AM To: Douglas Garstang Cc: Juha Heinanen; users@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@oneeighty.com wrote:
-----Original Message----- From: Juha Heinanen [mailto:jh@tutpro.com] Sent: Sunday, June 04, 2006 11:01 AM To: Douglas Garstang Cc: Bogdan-Andrei Iancu; Sam Lee; users@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@openser.org http://openser.org/cgi-bin/mailman/listinfo/users
-- Greg Fausak greg@thursday.com
_______________________________________________ Users mailing list Users@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
-
Douglas Garstang -
G.Jacobsen -
Juha Heinanen