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

[Izzy Blacklock]

On Sunday 23 Mar 2003 8:07 pm, Dave Hall wrote:
> > 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

Your rigid policy does make sense for trying to maintain a quality product.  
Given the overall functionality and quality of phpgw, it's obviously working.  
Such rigid policies do however slow production.  I'm not saying this is a bad 
thing.  I'm thankfull for the overall quality of the project.  

I'm beginning to understand how a project like Axisgw could have come about 
though.  I don't know the story, but I'm willing to bet it centres around a 
disagreement on this rigid policy.  Of course, I could be completely wrong.  
It doesn't matter either way.  It does however cause me to view Axisgw in a 
different light.  

Perhaps it is a good thing to have two projects (fork or not); one with rigid 
policies and focus on quality, the other more open and willing to accept 
"bleeding edge" additions.  This was the idea behind the samba fork and it 
turned out to be a win-win situation for everyone involved.  

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

This submission procedure makes sense for a polished production release.  It 
doesn't lend itself very well to open collaboration though.  Perhaps the 
Axisgw documentation project can serve as the repository for open 
collaboration for the more polished phpgw documents?

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

I have learned a great many things from bad/useless advise.  At the very 
least, bad/useless advise often prompts others to explain why something is 
bad/useless advise; but only if someone wrote it in the first place! :)

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

I look forward to playing with it.

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

Sadly, I have wasted hours hunting for even a scrap of usefull info in my 
efforts to get different parts of phpgw (and other projects for that matter),  
working.  On many occasions I've just simply given up due to a lack of time 
to deal with it.  I tend to be one for reading docs, searching mailing lists, 
googling, and reading source code long before I post questions.  Perhaps I'm 
too concerned with looking foolish with a stupid question.  As a result, I'm 
more then grateful for a poorly written doc that helps me through a problem.  

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

I am interested in the idea.  Of course that would hinge on the idea that a 
second wiki is created or the Axisgw wiki (assuming they are in agreement) is 
used for a "development version" of the documents.  I am in agreement with 
the idea of having strict controls on the "official" documents, but IMHO, 
open collaboration is necessary to allow all interested parties to become 
active participants in improving the documents.  Rigid rules tend to scare 
people with usefull contributions away.  

If this sounds like a workable solution, e-mail me direct to discuss details 
of what your expectations are for the role.

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

I understand the policies and agree with the reasons.  The red tape would 
likely have put me off in the past, but a rash of recent problems I've had 
related to poor or none existent documentation has strengthened my resolve to 
do something about it.  In the past I probably wouldn't have even bothered 
asking how to post to the wiki.

I've decided to take Adam up on his offer to post to the Axisgw wiki just 
because it's the easy way out.  Once the document is finished and meets the 
criteria for the "official" phpgw documents, it can be transfered.  

...Izzy