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...
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
On Fri, Sep 20, 2013 at 11:10 PM, Michael Heydekamp listuser@freexp.de wrote:
Hello Thomas,
Hello Michael
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...
I don't take this as a disappointment. Reading through all the text takes its time and we're open for responses at any time :-)
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?).
Feel free to fix these glitches directly via Transifex. Although some of us speak German, we don't have the time to verify all translations and we therefore trust our translators - or the reviewers - to choose the right words.
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).
Don't worry, this won't delay the release. But we have agreed to put it on the road map and thus we should at least have "something".
- 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...).
We'll definitely don't go any deeper into the login process but I guess it belongs there just for the sake of completeness. But I absolutely agree with you that some settings need more explanation.
- 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.
You're not the first to suggest this but context-sensitive help isn't that simple to add because of the very flexible skinning approach Roundcube has. We have "some" context support when embedding the docs with the help plugin. That will at least jump to the chapter that fits the current content of the Roundcube window when opening the help.
Kind regards, Thomas
Hi Thomas,
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.
I want to add a nginx web server section in the Getting started => Configuration section.
Is this ok or do you want to add Getting started => Configuration => web server => nginx ?
Best regards
Aleks
On Sat, Sep 21, 2013 at 11:32 PM, Aleksandar Lazic al-roundcubedev@none.at wrote:
Hi Thomas,
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.
I want to add a nginx web server section in the Getting started => Configuration section.
Is this ok or do you want to add Getting started => Configuration => web server => nginx ?
Roundcube is actually meant to run on a default webserver configuration. Thus I suggest to place the Nginx configuration under "Further reading" which I just prepared here: http://trac.roundcube.net/wiki/Howto_Config/Webservers
Thanks!
Thomas
Am 23-09-2013 14:50, schrieb Thomas Bruederli:
On Sat, Sep 21, 2013 at 11:32 PM, Aleksandar Lazic
[snipp]
I want to add a nginx web server section in the Getting started => Configuration section.
Is this ok or do you want to add Getting started => Configuration => web server => nginx ?
Roundcube is actually meant to run on a default webserver configuration. Thus I suggest to place the Nginx configuration under "Further reading" which I just prepared here: http://trac.roundcube.net/wiki/Howto_Config/Webservers
Thanks, I will start there.
Cheers Aleks
-
Aleksandar Lazic -
Michael Heydekamp -
Thomas Bruederli