[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>:
>>
>>> 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.

Agreed.

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

Why not? Like I said, the current libraries pages on the website are  
just a start and could definitely be improved. The library's start  
pages should contain content like the Routes and Imap pages on  
dev.horde.org. And the overview should be more structured and cover  
better the different state of the libraries.

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

Well, not being happy with the design it not a valid reason to build  
another website. We agreed on this design and are going to stick with  
it for a while. There is no design everybody would be 100% happy with,  
but consistency is much more important.

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

The used to be updated automatically when we had our own CI server.  
Since then, this has to be done manually. We need to get the automated  
updating working again, if we start to write more documentation,  
because this will be updated at the same time.
-- 
Jan Schneider
The Horde Project
http://www.horde.org/