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

[Izzy Blacklock]

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.  

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.

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!  

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.  

> 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.  

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.  

...Izzy