[Owncloud] Suggestion: general help framework
foss at christian-reiner.info
Tue Sep 11 13:41:18 UTC 2012
> > 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
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 ]
More information about the Owncloud