Hello Thomas,
it's a pity and a bit of a disappointment that nobody did respond to your post yet. A decent piece oft software such as Roundcube deserves a decent documentation, and your work is definitely a good start and approach (well, no, a lot more than just that!). And I know what I'm talking about, writing the docs is often even more complex, time-consuming (and sometimes even annoying) than "just" coding the stuff...
So I'm happy to see that documentation is important to Roundcube. And of course I'll be happy to contribute (as I'm not able to contribute to the code anyhow), if ... well ... "I wouldn't be dancing on too many weddings" currently (German saying). I'll have to see, I didn't even find the time yet to work on some awkward German translations of the UI (e.g. "Popups als Standard Windows behandeln", who the hell did translate THIS?).
I had just a quick look at your valuable and comprehensive work, some general comments and questions:
- The release of RC 1.0 should not wait for a "perfect" documentation, not
even for any documentation at all. Although documentation is important and I'm encouraging it (see above), the basics of Roundcube (i.e. reading/composing e-mail) can be used even by dumbest users without any documentation. This speaks for itself (for Roundcube, of course).
- Rather than starting with the documentation of the simple and
self-explaining stuff (e.g. how to login into Roundcube), I'd more focus on the not-so-obvious issues. Such as "Handle popups as standard windows" (the "Popups als Standard Windows behandeln" which I mentioned above already). This definitely needs explanation, as the average user won't have any idea about the concrete consequences of this setting. BTW: This item is not existent in the current documentation http://roundcube.net/doc/help/0.9/en_US/settings/preferences.html at all yet (probably because it's probably not existent in 0.9, but as we're speaking about the 1.0 roadmap, it should be there...).
- Having said that, would it technically be possible to implement something
like a context sensitive help for each config item, available via right click, hovering, <F1> key, whatever...? This could be more helpful than loading a full documentation where you would need to search for your current issue first. Office 2000 did have that, in later versions M$ did drop it, and to me this was a severe regression. Or take the help file of Total Commander, invoked with <F1>: Looks ancient and ugly, but the context sensitive CONTENT is extremely helpful and comprehensive.
So much for today, thanks again and cheers,
Michael Heydekamp Co-Admin freexp.de Düsseldorf/Germany
Am 19.09.2013 18:30, schrieb Thomas Bruederli:
Hello folks
One item on the 1.0 roadmap is to improve documentation for Roundcube. I recently started some efforts to achieve this. Now I'd like to ask you for proof-reading, review and contribution.
First, I tried to clean the wiki pages that describe Roundcube's installation, configruation and upgrading. Please review the pages from the Trac wiki [1] listed under "Getting Started". As you can see, there are still some "TBD." present. Also, the FAQ page is totally outdated and should be re-written completely.
Everybody is welcome to make corrections and additions directly on the wiki.
Second, I started to write some end-user documentation AKA online help. The pages are written in reST and generated with Sphinx which I found to be very handy for this task. I therefore created a new git repository [2] where all the sources are maintained and tried to summarize it in the README file and on our wiki [3].
The help docs are structured in a way to allow additional contents from plugins to be integrated. The idea behind all this is to provide a framework what will let you generate your individual online help files that describe all the components you chose for your Roundcube installation, even with screenshots from your custom skins. The generated files can then be linked into the help plugin with context-sensitive deep-links [4].
A first release of the online help for version 0.9 can be found here: http://roundcube.net/doc/help/0.9/en_US/
Again, I'd like to invite you all to read through these documents and make corrections or additions by sending pull requests to the roundcube/roundcubemail-helpdocs github repository.
Once we feel comfortable with the English version, translation into other languages can start.
Thank you all for your support!
Thomas
P.S. The help docs as you can see them online are sponsored by Kolab Systems and the Kolab Groupware project as they basically paid me for writing them. Thanks a lot for this, guys!
[1] http://trac.roundcube.net/wiki [2] https://github.com/roundcube/roundcubemail-helpdocs [3] http://trac.roundcube.net/wiki/Online_Help [4] https://github.com/roundcube/roundcubemail/blob/master/plugins/help/config.i... _______________________________________________ Roundcube Development discussion mailing list dev@lists.roundcube.net http://lists.roundcube.net/mailman/listinfo/dev