[dev] Fancy Horde/Imap_Client documentation

[Michael M Slusarz]

Quoting Jan Schneider <jan at horde.org>:

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

As for the first part: that is a matter of personal taste, I guess.   
Maybe I'm getting old, but both the text size and color are somewhat  
difficult to read.

As for the second part: I don't disagree about this either.  But the  
last time I tried to add something to the website, it took me an hour  
to figure out the whole setup and where to place stuff to actually get  
it to display.  I would much rather waste my time writing  
documentation than trying to figure that out again.  If someone wanted  
to start the process and make it easy to add content - that would be  
great.  But I'm going to stay out of the generation side of things.

>> (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.

I will try to take advantage of writing the more low-level usage  
examples using ReST and package with the library (I'm got a flight  
next week, which means several hours of dead time I could take  
advantage of).  But if this is not going to show up on the website,  
that sort of defeats the whole purpose of it.

michael

___________________________________
Michael Slusarz [slusarz at horde.org]