[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>:
>
>> Quoting Jan Schneider <jan at horde.org>:
>>
>>> 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.
>>
>> ...except this is not what I am looking for.  This:
>>
>> http://www.horde.org/libraries/Horde_Argv/docs/README
>>
>> is not a useful format for *advertising* a component, IMHO.
>
> It's just one part. Agreed, the docs for Argv are only for  
> implementing it, not for advertising it. But that's all about *what*  
> we write, not where.
> http://www.horde.org/libraries/Horde_Argv/library is where the  
> advertising should go, with more detailed documentation in  
> http://www.horde.org/libraries/Horde_Argv/docs.

One of the comments I received was that http://www.horde.org/libraries  
is pretty much worthless from a "What does Horde have to offer  
approach."

* Way too information dense for a portal page for people looking to  
see whether our software will be useful for them.  It is presented  
more as a way to find documentation on a library that you already know  
exists.

* There is no distinguishing between our "glue-ish" libraries that  
would be of dubious value outside of Horde (Support, Mime_Viewer, even  
Prefs) vs. our libraries that blow away what PEAR can provide or, in  
cases like ActiveSync or Imap_Client, that *anybody* can provide.

>> I am NOT trying to document the entire library.  I'm trying to draw  
>> people into using it - or at least getting the word out.  I just  
>> don't think reST is appropriate for this.  At least that's what  
>> potential clients are telling me.
>
> I don't understand what reST has to do with this. It's just an  
> intermediate format, like the wiki markup. It's designed to be  
> readable as-is though, so it's fine for bundling as technical  
> documenation with the package. But at this point, the user already  
> downloaded the libary and wants to use it, so that's fine.

I don't have a problem with that.  Maybe I'm confusing what you were  
saying previously: I don't want this rest documentation to be the ONLY  
documentation available and/or the initial presence.  We can use this  
as the default for many (most) of the libraries.  But there needs to  
be a way to allow a better (read: prettier) way of advertising our  
premium libraries.

In short, there is no way that this presentation:

http://www.horde.org/libraries/Horde_Routes (assuming it had all  
documentation)

can be deemed to be superior (or even as good as) this:

http://dev.horde.org/routes/

So maybe this just comes down to the issue I have with our main  
website design being too busy, distracting, and hard to navigate.

(Aside: all the versions in the libraries Download pages are way out of date).

michael

___________________________________
Michael Slusarz [slusarz at horde.org]