[dev] Re: Horde 3 docs and framework capabilities

[Greg Rundlett]

This is a multi-part message in MIME format.
--------------060600080005090605070108
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Michael M Slusarz wrote:

>Quoting Greg Rundlett <Greg.Rundlett at savaJe.com>:
>
>  
>
>>I am finding a real lack of documentation on the Horde, perhaps due 
>>in part to the fact that 3.x is relatively new.
>>    
>>
>
>Have you tried: http://dev.horde.org/ ?
>
>  
>
Please don't take my comments the wrong way.  This post is meant to be 
constructive. 

I have been frustrated recently by *many* open source projects that are 
'successful' in that they have a decent community and adoption, but that 
still don't have good documentation.  As an observer of the Tiki[1] 
project for a long time, I know the difficulty with producing good 
documentation, made all the more challenging when things evolve rather 
quickly.  I decided to write this post because I hope that the existance 
of API docs does not lure horde developers into complacency with the 
belief that there *is* documentation for people looking to use their 
code.  I am writing this post to encourage all Horde developers and 
contributors in whatever capacity to do what they can to create more 
documentation for the project.

Greg Beaver could attest that I am a big fan of phpDocumentor, and he 
would also point out (as he does in the tutorial on using 
phpDocumentor[2]) that it is only a tool that helps create good 
documentation.  There are so many files, classes and methods in a large 
project like Horde, that reading API docs is not a practical way of 
getting familiar with the code and how to use it.  For the horde, the 
API docs need to serve as a reference, not a guide.  Even then, there 
are many gaps in the API docs that don't make for good reading. 

Ideally, the code comments would be full of reference information, and 
examples so that the API docs *would* serve more as a guide than mere 
reference.  It's a difficult task to get everyone to do it, and some 
folks are better trainers than others so there are varying degrees of 
quality in documentation depending on who wrote the documentation.  (I 
myself still haven't taken time to fully learn how to incorporate the 
examples and references that way that they are intended to be used by 
the phpDocumentor system.)   What needs to be added are things like 
Jan's step-by-step walkthrough of accomplishing a task (creating an 
application using the Horde framework).  Reference architecture 
diagrams, program flow and data dictionaries, etc.

The wiki is a tool that has been used successfully by both Tiki and 
Seagull[3] to address "Howto", and reference information.  The benefit 
being that community members who do not necessarily contribute to the 
code, can still write up a story of "how I did X with the horde".  The 
downside is that organizing and maintaining accuracy can be a challenge, 
plus it's not coupled with the code, so it's bound to fall out of date 
if nobody maintains the wiki.

One of the problems I've seen with the Horde documentation is that the 
Administrator FAQ is badly out of date (still referencing things like 
phplib and 1.X versions of the horde).  I understand the need to keep 
this documentation for users who for some reason do not upgrade their 
installations, but surely this information needs to be separated out 
into version-specific files so that as a new (3.x) user, I don't need to 
read through and be confused by old/contradictory information.

I am sure that Horde developers are familiar with these issues, and 
obviously there is only so much that any single person can do.  I am 
sure that I am 'welcome to write the documentation' or contribute to the 
solutions instead of whining about the problems.  Actually, I am trying 
to help by opening this discussion. :-)

[1] http://www.tikiwiki.org
[2] 
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.pkg.html
[3] http://seagull.phpkitchen.com/docs/wakka.php?wakka=HomePage

-- 
Greg Rundlett

Release Engineering Team
SavaJe Technologies
(978) 259-2029

[random sig fortune]
transparent, adj.:
	Being or pertaining to an existing, nontangible object.
	"It's there, but you can't see it"
		-- IBM System/360 announcement, 1964.

virtual, adj.:
	Being or pertaining to a tangible, nonexistent object.
	"I can see it, but it's not there."
		-- Lady Macbeth.


--------------060600080005090605070108
Content-Disposition: attachment;
 filename="Greg.Rundlett.vcf"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit

A non-text attachment was scrubbed...
Name: Greg.Rundlett.vcf
Type: text/x-vcard
Size: 334 bytes
Desc: not available
Url : http://lists.horde.org/archives/dev/attachments/20050406/a9ed62ac/Greg.Rundlett-0001.vcf

--------------060600080005090605070108--