[dev] Fancy Horde/Imap_Client documentation

[Michael M Slusarz]

Quoting Jan Schneider <jan at horde.org>:

> Zitat von Michael M Slusarz <slusarz at horde.org>:
>
>> Finally.  It's about time.
>>
>> Initial implementation has been placed here:
>>
>> http://dev.horde.org/imap_client/
>>
>> (Looks a bit like the Routes documentation for some reason...)
>>
>> Not sure if this is the best place to store this.  Comments  
>> welcome.  And ideas how to link from our main www.horde.org pages  
>> is also welcome.
>>
>> Also would be interested to hear thoughts on what else to put on  
>> there.  Obviously the examples page needs to be fleshed out more,  
>> but I'm not going to spend the time doing too much unless/until  
>> people actually start using it.  So if anybody wants examples of a  
>> certain feature, now is the time to speak up.
>
> That's a great start! The examples could use a few more inline  
> comments, to better explain which variable holds what, and what each  
> used method returns.

Right now I have to manually convert all the code to formatting (by  
putting in SPAN classes - ugh).  I really need either an automated way  
of doing this (I'd rather not have a javascript solution) or some  
location where I can insert the code and then copy/paste the HTML  
source.  That's really what was preventing me from providing other  
examples.

> Generally I think the documentation is spread in too many places.  
> While the Routes layout looks nice, it's hard to maintain. And we  
> already have the tools in horde-components to *distribute* docs to  
> several places, while *maintaining* it in a single place.
> Library docs should be completely maintained in the wiki. It's  
> easier to edit, and contributions are much easier too. The  
> horde-components script can pull those docs into the package's doc/  
> folder. From their, they will build website docs on www.horde.org.  
> See Horde_Argv for an example.

Unfortunately, I'm going to have to disagree with you.

As someone who has used the Horde_Argv documentation on the wiki, it  
*was* useful in terms of figuring out some of the details.  But there  
is NO way the Horde_Argv documentation, as presented on our wiki,  
would ever convince me to use that library over some other competing  
library.  Horde_Argv may be the most professional, bug-free,  
comprehensive argument parsing library out there.  But I would never  
know that from the documentation.  This is a limitation of using a  
wiki as the main page.

What I am trying to address is concerns I have heard from multiple  
different clients/potential clients when asking about  
Horde_Imap_Client.  Namely, they were both unaware and/or unsure of  
the quality/professionalism/maintenance of the code because there  
wasn't a "pretty" website for them to go to for a quick synopsis.  It  
is extremely frustrating to hear people talking about their necessity  
to continue to use the c-client extension because there is no other  
PHP solution that provides IMAP connectivity.  I have pointed them to  
the wiki pages on Imap Client in the past, but nobody is impressed.   
For those of us that care about functionality and performance, fancy  
graphics and buzz words is a lame way to advertise your products.  But  
it works -- or at least it doesn't hurt.

This is a limitation we have all discussed before - sometimes, we just  
don't advertise what we offer well enough.  Having API documentation  
is all well and good, but it is useless unless we can provide  
documentation to pull people in first.  That's the goal of this  
separate page.  That's not something the wiki can ever hope to  
replicate.

michael

___________________________________
Michael Slusarz [slusarz at horde.org]