Re: [Phpgroupware-developers] Adding to the phpgw wiki...

[Dave Hall]

Izzy Blacklock <address@hidden> wrote:

> On Sunday 23 Mar 2003 4:00 pm, Dave Hall wrote:
> > Izzy Blacklock <address@hidden> wrote:
> 
> > > I'm currently working though a number of problems getting phpgw
> > > working with
> > > LDAP authentication.  The main source of my problems seems to be
> > > the lack of
> > > documentation.  I'd like to help change this.  A wiki is an ideal
> > > way for
> > > people to contribute to the development of the phpgw
> > > documentation.  Locking
> > > all the pages makes this impossible.
> >
> > We welcome contributions, but we must see some results before 
> giving you
> > rights to change things.  This goes for all developers, be they 
> coders,> support crew or documenters.
> >
> > > I can understand wanting to keep an overall level of quality to
> > > the wiki
> > > contents, but having a poorly written base for others to improve
> > > on would be
> > > better then no documentation at all.  May I suggest at least
> > > starting a
> > > contribution page which can be edited freely?
> >
> > At the moment only developers have write access to the wiki.  
> The ACLs
> > don't currently allow this, and yes quality is of major 
> importance to
> > us.  I would suggest that you create the document, put it on a 
> website,> we will check it and if it is up to scratch then we will 
> add it.
> 
> I can understand the need for quality documents, and support the 
> idea of 
> restricting access to the finished document.  However, the current 
> state of 
> documentation is very poor and the policy as you've described 
> makes it 
> difficult for people like myself to help correct this.  

I understand this, but also we need to ensure the quality of our
product.    No only do out docs need work, but we also have a long list
of unmaintained applications.  We are moving and updating all of our
documentation to the wiki.  The policy is spelt out in an old document -
http://docs.phpgroupware.org/developer.php

> 
> First off, I did not find this policy or any details anywhere on 
> how to 
> contribute to the documentation efforts.  Maybe I missed 
> something?  Second, 
> the requirement to put your documentation up on your own server 
> and submit it 
> for evaluation defeats the purpose of having a wiki.  There are no 
> guidelines 
> for what is required to be "up to scratch" so I could put a bunch 
> of work 
> into a document and have it rejected.  This doesn't help someone 
> who may have 
> benefited from even a small piece of information I may have put 
> into the 
> document.

The reason why I suggest you put the documentation on a server is so all
developers can review it.  Alternatively you could put the patch on
savannah - https://savannah.gnu.org/patch/?group=phpgroupware

As for the asessment, here is the basic criteria that would be used:
* Is it accurate?
* Is it clear?
* Is it well written?
Yes to 3 three then it is in, if not you may get some comments on
changes, or it may editted.

> 
> I've benefited from many poorly written and hard to understand 
> documents that 
> someone through together in the hopes it would be usefull.  Sure 
> these are 
> not of the quality I would consider good for official documents, 
> but they 
> were enough to help me through a problem.  I'll take that any day 
> over no 
> documentation at all!  

I have spent hours reading bad/useless advise while googling.  This is
what we want to prevent.

> 
> Wiki's, and Faq-O-Matics are an ideal interface for users and 
> developers alike 
> to contribute to the documentation efforts of a project.  There is 
> a risk 
> that they will fill up with content of questionable usefullness, 
> but the 
> overall benefit is better then nothing at all.  Poorly written 
> document can 
> be improved upon by others and obsolete or erroneous documents can 
> be removed 
> or replaced.  

I think wikis are good, but not all wikis are publicly editable.  As for
faq-o-matics, I have just ported phpbrain to phpgw.  This should be
available to users on our website in the coming days.  You can download
either of these apps too - although they are officially unsupported at
the moment.

As for something is better than nothing, I disagree, I spend enough time
dealing with bad code, I don't want to have to deal with bad docs too. 
We currently lack a document team coordinator, if you are interested in
this role, let me know, we would appreciate any contribution you can make.

> 
> > But axisgw is not phpgw.  There wiki is designed for ideas, ours is
> > designed for documentation.
> >
> > I hope you can understand the need for such policies.
> 
> I do understand the need for controlling what goes into the 
> "official" 
> documentation.  However, I think the current state of the 
> documentation is a 
> good indication that more help is needed.  A less formal way for 
> people to 
> contribute would go a long way to fill this need.  

Our wiki will contain offical documentation and planning docs.  I am
happy to acknowledge we need help, but we need processes to ensure
quality.  We do not give instant CVS access to people because they have
an idea, and imho the same goes for docs.

> 
> May I suggest providing a second, development wiki for 
> contributions. In this 
> way, you could continue locking down the "official" documents 
> while creating 
> a "development" version which anyone can contribute to.  Once 
> content in the 
> "development" version was "up to scratch", it could then be 
> transfered to the 
> official document.  This would make it easy for someone to slap a 
> document 
> together quickly and for others to benefit from it immediately.  

We can look at this.  I will discuss this other developers.

Please don't let the red tape put you off.  The policies are there for a
reason.

Cheers

Dave

dave.hall.vcf
Description: Card for <dave.hall@mbox.com.au>