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