[Owncloud] Suggestion: general help framework

[Klaas Freitag]

On 11.09.2012 16:41, Christian Reiner wrote:
>>> On 11.09.2012, at 07:22, Michael Gapczynski <mtgap at owncloud.com> wrote:
>>> I like the idea Christian.
+1

> 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.
I would suggest to package all available user docs whenever we package, 
ie. at release time.

Advanced: To update it on installed ownClouds, we could have an ownCloud 
doc server with all documentation on it. If an installed ownCloud has 
Internet access it can verify that its documentation is up to date and 
update if needed.
>
> 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.
True, but there is another aspect to keeping docs in git: Documentation 
writer usually do not like to work with git. As the most crucial point 
of the whole idea is to actually _get_ good documentation (who of you 
devs has actually written extensive user docu?), we should take care 
that doc writing is as easy as possible. From my experience from 
openSUSE where we started something similar that works best with an open 
wiki with a review process.

> 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.
Very good.

regards,
Klaas