[Owncloud] Suggestion: general help framework

[Christian Reiner]

Hello all, 
this message is something like a request for comments, happy about all 
remarks, ideas and criticism from you. 

Whilst implementing the new settings popup mechanism inside apps as agreed 
upon for the future into my Shorty app I stumbled over the requirement for a 
better user assistance. INside that app and in general. Some 5 month ago I 
made a suggestion about that in the owncloud forums which I would like to pick 
up again: 
http://forum.owncloud.org/viewtopic.php?f=3&t=2332&p=3706&hilit=arkascha#p3706
I suggest to implement such feature, either as a core component or preferable 
as a standalone app if efficiency permits. Since such general framework is 
something that only makes sense if it is generally accepted, I would like to 
ask for feedback prior to starting an implementation attempt by myself. 

Currently ownCloud relies on ordinary users to find out about the two ownCloud 
web ressources, the forum, irc channels, bugtracker and mailinglist to get 
help and answers to questions. Whilst nothing is wrong in using these means it 
certainly is a non-trivial threshold for ordinary users, especially in a 
situation where typically advice is sought: new environment and concepts. 
Instead I think it makes sense to take those users by the hand and offer help 
or at least entry points at exactly that place where they currently deal with: 
inside the ownCloud UI. For me this means two aspects: 1.) a meaningful 
welcome screen as entry point and 2.) a help button that actually offers non-
trivial information in a context sensitive way. So I suggest an additional 
help button between search widget and logout button in the header. I would use 
a question mark as label. This help button offers a popup (like the new in-app 
settings dialogs) holding several tabs: 
- something general about ownCloud: version, homepage and other urls etc
- something about this specific installation maybe
- something general about the currently active app: usage, concepts, ...
- context sensitive assistance for the current dialogs/activities/options

This is all not too difficult, it is more a question of condensing the 
available information in an appealing way :-)
However there is one aspect that needs to be crafted thoughtfully: 
when all apps are to use a general help facility an clear and stable interface 
has to be agreed upon. An interface that allows to register that information 
to be offered according to the current context. Two strategies come to mind: 
1.) slots offered by the help app: registerContextHelp() or similar
2.) slots offered by all apps and used by the help app
3.) a general 'canvas facility' that allows apps to register context 
information in a dynamical manner on the client side
The information should be localized, especially the tab titles. And it might 
make sense to implement a few backend engines to support different 
formats/ressources: file vs. web reference, html vs. plain text vs. wiki code. 
A nice bonus would be a feature that allows to edit those help texts or add 
pages or tabs for the own installation. 

The participation effort for app developers would consist of two things: 
1.) write help / information texts and translate them (get them translated)
2.) to register those texts, probably stored as separate files per aspect in 
an additional folder called 'help'. 

Ok, this is my suggestion. 
Any comments?
Thanks!

-- 
Christian Reiner (arkascha)
[ foss at christian-reiner.info ]