IMO maintaining outside of platform and out of sync an application that is supposed to help using it is going to be a nightmare. It's pretty much impossible to have demo content in it for any feature more recent that its minimum supported version.
On Thu, May 18, 2017 at 5:15 PM, Vincent Massol <[email protected]> wrote: > Hi devs, > > We have 2 topics to decide: > > * Topic 1: Right now we have 2 help applications. We need to decide if we > merge them or not. > * Topic 2: Decide if we keep the Help Center app in contrib or if we move it > in platform. > * Topic 3: Decide if we fold the Sandbox into the Help Center > * Topic 4: Decide how we handle data created/modified by users when we > upgrade or for newcomers. > > Re topic 1, my preference goes to having a single help application and fold > what’s currently in the platform help app into the Help center. There’s no > reason that knowing how to edit a page would be more or less core than > knowing the syntax markup or the Tips Panel. > > Re topic 3, I don’t think that the sandbox app is really that useful as a > standalone app and I would be for merging it into the Help application. > > Re topic 4, there are 2 issues I can think of: > - when new users come in, if the pages that are supposed to be modified > (sandbox + the 2 bundled AWM apps) have been heavily modified, then newcomers > won’t see the default content and could just be seeing defaced content. > - if the pages have been modified by the user + by the help app then on XWiki > upgrade there’ll be conflicts. > > One idea for topic4 is to have the Help app spawn new pages (ie pages not > bundled by the Help app itself) for users to try them out, by having some > “try it out” button. > > Re topic 2, the issue with keeping the help center app outside of platform is > that we need to support documentation for multiple versions of XWiki. For > example, we modified the page menu in Xwiki 9.4 and there are over 10 > screenshots to update. However users of XWiki 8.4 (for ex) can also install > this app and if they get the new documentation, it won’t match what they see > in their wiki. The same can be said with the new notification feature for > example. > > The advantage of moving it in platform is that it’s in sync with the platform > (ie less work) but we should only document platform features in it. It also > means longer release times since it’s linked to the release of platform. Note > that the rationale for having it in platform would be that platform help is a > core feature. > > We could (and probably should) offer some places in the Help Center so that > Extensions could plug their help. And we could probably refactor a bit the > current content of the help center to move help for feature in the extension > UI part of those extensions. > > Considering all aspects I think my preference goes to having it in platform > since I don’t think we have the manpower to maintain doc for all versions of > XWiki. > > WDYT? > > Thanks > -Vincent > -- Thomas Mortagne
