[Phpgroupware-users] Re: docs, docs development, and development docs

[Dave Hall]

IMHO this is a discussion for the developer list ... moving it to there
:)  Please everyone reply on the dev list.

Brian Johnson <address@hidden> wrote:

> I was wondering if there could be some discussion (and conlcusion) 
> about how we
> could set up a system/procedure to allow easier creation of 
> documentation
> My personal preference is for wiki's since they are easy to edit 
> and add to as a
> group, a little at a time, but I don't know if that would satifsy 
> all of our needs.
> 
> To start discussion, what about this proposal:
> 1. we have a public access (read only) wiki at 
> docs.phpgroupware.org that only
> authorized personel could edit

This is what I have already setup.  I also plan on setting up
docs.phpgroupware.org as a sitemgr site, so we can have more formalised
docs site.  More on this shortly. 

> 2. we have a public access (read and write) wiki as a development 
> playground as a
> subsection of docs.phpgroupware.org

I support this idea also.  The main issue is how we do this.  The wiki
app does not support full acls atm.  Also it is not easy to have 2 apps
called wiki on the same install.

As an alternative, I would like to propose the following.  All docs are
created in docs.phpgroupware.org/wiki and the creator can request that
they are included in docs.phpgroupware.org.  They can continue to
maintain them on the wiki and we just import them.

2 things which need to be considered, licensing of the docs and
copyright.  IMHO all docs should be copyright FSF under the FDL (see
http://www.gnu.org/licenses/fdl.html ).  This is easy to do, but how we
make sure it done when people contribute to an open wiki is a seperate
issue.  I will discuss with some GNU people some standard text that we
could put above the textarea so people consent to this when submitting docs.

> 
> The wiki's should be organized into Users and Developers sections 
> to help organize
> the info but all of it should be public readable.

I think our documentation needs a complete review - and a coordinator,
this sounds to me like you are volunteering ;)

> 
> I understand that some people would like the docs included with the 
> app.  Is it
> practical to make html pages from the wiki pages automatically?  

Yep phpdocumentor creates nice looking HTML docs.

> How should this be
> done?

it can be done via script - nightly cron even.

> 
> What about inline code docs?  I know some developers would like them.

yep phpdocumentor.  During the last long discussion on documentation,
most people thought that phpdocumentor was the was to go, instead of the
Apple standard.   This is something I support. Dan even stated he used
phpdoc - which I discovered is incorrect - but it is easy to convert.  I
have documented the base sessions and db classes in the api with phpdoc
- although I have not tried to generate the docs.

Over to the masses.

Cheers

Dave

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