[Owncloud] Suggestion: general help framework

[Christian Reiner]

> > On 11.09.2012, at 07:22, Michael Gapczynski <mtgap at owncloud.com> wrote:
> > I like the idea Christian. We could also use some improvements on the
> > documentation on the website. For the welcome page, could we show a nice
> > overlay for a new user with a short guide. How to upload files, share a
> > file, moving files, setup webdav client, etc. Rather than the user
> > stumbling around. This content could probably be the same as the help
> > section.

> On Tuesday 11 September 2012 13:53:33 Frank Karlitschek wrote:
> Perhaps I´m missing fantasy but I only see one option here. :-)
> We should have a basic help included in ownCloud for stuff like "how to
> upload" and "how to share." At the end the help text we add a "more" button
> than links to the website for more extensive documentation. The shipped
> short documentation has to be in git but this shouldn´t be a problem
> because this is only short anyways and the more extensive documentation is
> online. No?

You get a "yes and no" from my point of view  :-)

Using some basic packaged information as teasers as suggested by Frank sounds 
like a good compromise to me. It allows easy and frequent enhancements to the 
detailed information which is sometimes required. And it solves the problem of 
company internal ownCloud installations that are blocked from direct internet 
connection to fetch information in background: the users browser is simply 
forwarded in a transparent manner. 
If such basic information is packaged anyway it certainly makes sense to keep 
it in git, to treat it as part of the software. Nevertheless I would advise to 
keep app specific information inside the apps folder. 

However the ownCloud git repository cannot be the sole source of such 
information. That does not work for 3rd party apps. 3rd party apps simply 
aren't kept in the ownCloud git repository. Also these might have a different 
release schedule, acquire additional or revised features independent of OC 
releases. And there might be inter-app dependencies (one app adding a feature 
to another app). So the situation is less centric, more distributed here. 

This is why I suggested to create a way to allow apps to register help texts 
at runtime into a help framework. The framework is much more flexible this 
way. It would also make it easier for local admins to add own, locally 
relevant information to the framework and keep maintain that over upgrades. 

For such architecture it is of vital importance to have a good and stable api 
design. A design everyone accepts. A design used inside apps, internal or 3rd 
party. Otherwise we risk to get an information fragmentation just as we 
currently see it with the different online resources. This would be a bad 
thing.  
I would like to get as much feedback about that api design as possible before 
I start an implementation. Especially feedback from app authors. 

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