[RCD] Documentation efforts

Michael Heydekamp listuser at freexp.de
Fri Sep 20 23:10:33 CEST 2013


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.inc.php.dist
> _______________________________________________
> Roundcube Development discussion mailing list
> dev at lists.roundcube.net
> http://lists.roundcube.net/mailman/listinfo/dev


More information about the dev mailing list