18 May
2017
18 May
'17
5:15 p.m.
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
19 May
19 May
10:01 a.m.
New subject: [xwiki-devs] [Brainstorming] Remaining Help Application decisions
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 <vincent(a)massol.net> 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
10:10 a.m.
New subject: [xwiki-devs] [Brainstorming] Remaining Help Application decisions
On Fri, May 19, 2017 at 11:01 AM, Thomas Mortagne <thomas.mortagne(a)xwiki.com
wrote:
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.
I don't think we need to keep a low minimum supported version. We can
increase the platform version whenever we update the documentation, if it
is required.
>
> On Thu, May 18, 2017 at 5:15 PM, Vincent Massol <vincent(a)massol.net>
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
>
10:32 a.m.
New subject: [xwiki-devs] [Brainstorming] Remaining Help Application decisions
On 19 May 2017, at 10:10, Marius Dumitru Florea
<mariusdumitru.florea(a)xwiki.com
Yes indeed that would prevent users from installing a new version on an older XWiki.
BTW does EM supports suggesting the last compatible versions for your wiki? (AFAIK it’s
not implemented yet and would be nice for this use case).
Thanks
-Vincent
wrote:
On Fri, May 19, 2017 at 11:01 AM, Thomas Mortagne <thomas.mortagne(a)xwiki.com
wrote:
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.
I don't think we need to keep a low minimum supported version. We can
increase the platform version whenever we update the documentation, if it
is required.
> On Thu, May 18, 2017 at 5:15 PM, Vincent Massol <vincent(a)massol.net>
> 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
>
10:04 a.m.
New subject: [xwiki-devs] [Brainstorming] Remaining Help Application decisions
On Thu, May 18, 2017 at 6:15 PM, Vincent Massol <vincent(a)massol.net> 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.
I would keep the syntax help in a separate module that is a dependency of
the Help Center, in case some flavor wants only this and not the full Help
Center.
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.
The Sandbox is already a dependency of the Help Center. We could merge but
we could also keep it in a separate module.
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.
I think Thomas has worked on a feature to "reset to factory" any XAR
extension. That could help to restore the default content, either before
the upgrade or from time to time.
- 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 Help Center can have versions that match XWiki versions. It can stay in
contrib (I don't see it as core) and we release a new version when there
are significant changes.
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.
The Help Center is right now more about promoting a hand-picked list of
features (editorial work) rather than showing automatically help for any
extension you have installed.
Thanks,
Marius
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
10:09 a.m.
New subject: [xwiki-devs] [Brainstorming] Remaining Help Application decisions
On 19 May 2017, at 10:04, Marius Dumitru Florea
<mariusdumitru.florea(a)xwiki.com> wrote:
On Thu, May 18, 2017 at 6:15 PM, Vincent Massol <vincent(a)massol.net> wrote:
Yes but I don’t see any fundamental difference. It would just mean that only some features
would provide help at this stage.
I see it very similar to this page:
http://enterprise.xwiki.org/xwiki/bin/view/Main/Features
This pages contains 2 parts:
* A fixed part at the top listing topics that are more generic than just one extension
* But it has a big part that is contribute by extensions themselves (it offers a place for
extensions to contribute content).
Thanks
-Vincent
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.
I would keep the syntax help in a separate module that is a dependency of
the Help Center, in case some flavor wants only this and not the full Help
Center.
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.
The Sandbox is already a dependency of the Help Center. We could merge but
we could also keep it in a separate module.
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.
I think Thomas has worked on a feature to "reset to factory" any XAR
extension. That could help to restore the default content, either before
the upgrade or from time to time.
- 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 Help Center can have versions that match XWiki versions. It can stay in
contrib (I don't see it as core) and we release a new version when there
are significant changes.
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.
The Help Center is right now more about promoting a hand-picked list of
features (editorial work) rather than showing automatically help for any
extension you have installed. Thanks,
Marius
>
> 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
2677
days inactive
2678
days old
5 comments
3 participants
participants (3)
-
Marius Dumitru Florea -
Thomas Mortagne -
Vincent Massol