[dev] Fancy Horde/Imap_Client documentation

[Jan Schneider]

Zitat von Michael M Slusarz <slusarz at horde.org>:

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

Maybe I wasn't clear. I consider the wiki to be the source of the  
documentation, and doing what it does best: allowing easy editing and  
formatting of text. The location where we should point people to, is  
the website. The library section is just a start there and could  
definitely use some more love, but it's much better than maintaining  
yet another website.

So this is the workflow:
1) Editing in the wiki: http://wiki.horde.org/Doc/Dev/HordeArgv
2) Converting to reST:  
http://wiki.horde.org/Doc/Dev/HordeArgv?actionID=export&format=rst
3) Bundling with PEAR package:  
http://git.horde.org/horde-git/-/browse/framework/Argv/doc/Horde/Argv/
4) Building for website: http://www.horde.org/libraries/Horde_Argv/docs/README

Steps 2-4 are supported by horde-component.
-- 
Jan Schneider
The Horde Project
http://www.horde.org/