[Brainstormoing] Removing old "since" from xwiki.org

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

[Brainstormoing] Removing old "since" from xwiki.org

vmassol
Administrator
Hi,

I think we need to start removing old mentions on xwiki.org. It makes it harder to read xwiki pages (as a user has just reported, see https://forum.xwiki.org/t/how-to-increase-active-installs-of-xwiki/3132/6?u=vmassol).

Also we said we don't support documenting old stuff (we only support doc for LTS, stable and latest).

For example I just did this:
http://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationConcludingSteps/?viewer=changes&rev1=11.2&rev2=11.3 

Is that ok with everyone?

Thanks
-Vincent

Reply | Threaded
Open this post in threaded view
|

Re: [Brainstormoing] Removing old "since" from xwiki.org

Adel Atallah
Hi,

I think it makes sense to remove information related to XWiki versions
below the LTS one as long as the information is not required to do an
upgrade or the information can at least be seen in a release note or
somewhere else.

Thanks,
Adel


On Mon, Jun 18, 2018 at 1:19 PM, Vincent Massol <[hidden email]> wrote:

> Hi,
>
> I think we need to start removing old mentions on xwiki.org. It makes it harder to read xwiki pages (as a user has just reported, see https://forum.xwiki.org/t/how-to-increase-active-installs-of-xwiki/3132/6?u=vmassol).
>
> Also we said we don't support documenting old stuff (we only support doc for LTS, stable and latest).
>
> For example I just did this:
> http://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationConcludingSteps/?viewer=changes&rev1=11.2&rev2=11.3
>
> Is that ok with everyone?
>
> Thanks
> -Vincent
>
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstormoing] Removing old "since" from xwiki.org

Thomas Mortagne
Administrator
In reply to this post by vmassol
Sure, make sense.

I guess most document useless in >=LTS should be removed. Unless the
documentation is designed to give the version information of for
changelog stuff.

On Mon, Jun 18, 2018 at 1:19 PM, Vincent Massol <[hidden email]> wrote:

> Hi,
>
> I think we need to start removing old mentions on xwiki.org. It makes it harder to read xwiki pages (as a user has just reported, see https://forum.xwiki.org/t/how-to-increase-active-installs-of-xwiki/3132/6?u=vmassol).
>
> Also we said we don't support documenting old stuff (we only support doc for LTS, stable and latest).
>
> For example I just did this:
> http://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationConcludingSteps/?viewer=changes&rev1=11.2&rev2=11.3
>
> Is that ok with everyone?
>
> Thanks
> -Vincent
>



--
Thomas Mortagne
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstormoing] Removing old "since" from xwiki.org

Ecaterina Moraru (Valica)
If we were to export PDFs of documentation at a certain version than I
would agree with this.
Currently my feeling is that we are deleting information and not all our
users are on LTS or recent versions.

I agree is important to have the most simple and clear documentation, yet
it's bad that we don't provide versioned documentation.

Also, even cleaning now, it's a task that is very big and the info will get
deprecated in a year. If the language we use is using present tense, users
will still be confused 1 year later and still would not know about what
version that documentation is talking about. Especially since there is no
way we could validate documentation on year release.

I don't have a clear solution for this problem.
Thanks,
Caty

On Mon, Jun 18, 2018 at 3:44 PM, Thomas Mortagne <[hidden email]>
wrote:

> Sure, make sense.
>
> I guess most document useless in >=LTS should be removed. Unless the
> documentation is designed to give the version information of for
> changelog stuff.
>
> On Mon, Jun 18, 2018 at 1:19 PM, Vincent Massol <[hidden email]>
> wrote:
> > Hi,
> >
> > I think we need to start removing old mentions on xwiki.org. It makes
> it harder to read xwiki pages (as a user has just reported, see
> https://forum.xwiki.org/t/how-to-increase-active-installs-
> of-xwiki/3132/6?u=vmassol).
> >
> > Also we said we don't support documenting old stuff (we only support doc
> for LTS, stable and latest).
> >
> > For example I just did this:
> > http://www.xwiki.org/xwiki/bin/view/Documentation/
> AdminGuide/Installation/InstallationConcludingSteps/?
> viewer=changes&rev1=11.2&rev2=11.3
> >
> > Is that ok with everyone?
> >
> > Thanks
> > -Vincent
> >
>
>
>
> --
> Thomas Mortagne
>
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstormoing] Removing old "since" from xwiki.org

Thomas Mortagne
Administrator
To be clear I don't think it's a good id to remove the word "since".
There is often big differences between LTS and current stable. Simply
removing old since when hitting one is probably better.

On Mon, Jun 18, 2018 at 3:06 PM, Ecaterina Moraru (Valica)
<[hidden email]> wrote:

> If we were to export PDFs of documentation at a certain version than I
> would agree with this.
> Currently my feeling is that we are deleting information and not all our
> users are on LTS or recent versions.
>
> I agree is important to have the most simple and clear documentation, yet
> it's bad that we don't provide versioned documentation.
>
> Also, even cleaning now, it's a task that is very big and the info will get
> deprecated in a year. If the language we use is using present tense, users
> will still be confused 1 year later and still would not know about what
> version that documentation is talking about. Especially since there is no
> way we could validate documentation on year release.
>
> I don't have a clear solution for this problem.
> Thanks,
> Caty
>
> On Mon, Jun 18, 2018 at 3:44 PM, Thomas Mortagne <[hidden email]>
> wrote:
>
>> Sure, make sense.
>>
>> I guess most document useless in >=LTS should be removed. Unless the
>> documentation is designed to give the version information of for
>> changelog stuff.
>>
>> On Mon, Jun 18, 2018 at 1:19 PM, Vincent Massol <[hidden email]>
>> wrote:
>> > Hi,
>> >
>> > I think we need to start removing old mentions on xwiki.org. It makes
>> it harder to read xwiki pages (as a user has just reported, see
>> https://forum.xwiki.org/t/how-to-increase-active-installs-
>> of-xwiki/3132/6?u=vmassol).
>> >
>> > Also we said we don't support documenting old stuff (we only support doc
>> for LTS, stable and latest).
>> >
>> > For example I just did this:
>> > http://www.xwiki.org/xwiki/bin/view/Documentation/
>> AdminGuide/Installation/InstallationConcludingSteps/?
>> viewer=changes&rev1=11.2&rev2=11.3
>> >
>> > Is that ok with everyone?
>> >
>> > Thanks
>> > -Vincent
>> >
>>
>>
>>
>> --
>> Thomas Mortagne
>>



--
Thomas Mortagne
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstormoing] Removing old "since" from xwiki.org

vmassol
Administrator
In reply to this post by Ecaterina Moraru (Valica)


> On 18 Jun 2018, at 15:06, Ecaterina Moraru (Valica) <[hidden email]> wrote:
>
> If we were to export PDFs of documentation at a certain version than I
> would agree with this.
> Currently my feeling is that we are deleting information and not all our
> users are on LTS or recent versions.

Yes but we have to decide between:
* Make it simpler and nicer for new users coming in and on versions that xwiki.org supports
* Make is less nice for new users but nicer for old users using not supported versions of XWiki

So far we’ve decided to not keeping the documentation for old versions of XWiki, see https://www.xwiki.org/xwiki/bin/view/Main/Support#HSupportedVersions which says "You won't find documentation for old versions on this web site”.

> I agree is important to have the most simple and clear documentation, yet
> it's bad that we don't provide versioned documentation.
>
> Also, even cleaning now, it's a task that is very big and the info will get
> deprecated in a year. If the language we use is using present tense, users
> will still be confused 1 year later and still would not know about what
> version that documentation is talking about. Especially since there is no
> way we could validate documentation on year release.
>
> I don't have a clear solution for this problem.

Me neither and I don’t think there’s a magical solution :)

Note that now that we’ve removed the platform and enterprise wikis and moved the main doc under https://www.xwiki.org/xwiki/bin/view/Documentation/ it’s slightly easier to copy the documentation: we would need to copy this space when we do a release. Note that e.x.o would need to be handled too.

But that’s just the technical aspect.

In practice it’s a LOT of work to handle several versions as ElasticSearch is doing: https://www.elastic.co/guide/index.html

The work I can imagine:
* Whenever adding something new, need to decide in which doc version it goes. And right now we don’t have merge support in XWiki so it would need to be by hand
* When we do refactorings (so on the latest doc), and we need to merge to LTS or Stable we need to find the old place where it was

In any case it would take substantial more time to handle multiple versions (not even mentioning multiple languages ;)). And I don’t think we have a large enough participating community to allow for this….

<aside>
If you remember Caty, at some point, we discussed about implementing an app for doing this. In short it would be similar to the Release Notes app where you can add a new release change item (here it would be a new Doc item) and when you do so, you also enter info in the xproperty corresponding to the versions that apply to the doc item. Ofc you also enter the Category/Subcategories (or tags), etc.

Then you can browse a Categories/Tags, say “Installation” and “MySQL” and an XWik version (defaults to latest) and you’ll have a nice LT with all the doc items corresponding to that.

Ofc there are problems with this, for ex:
* coherent doc
* you must have one item doc per heading (to be fined-grained enough, works less well for tutorials types of documents)
</aside>

Thanks
-Vincent

> Thanks,
> Caty
>
> On Mon, Jun 18, 2018 at 3:44 PM, Thomas Mortagne <[hidden email]>
> wrote:
>
>> Sure, make sense.
>>
>> I guess most document useless in >=LTS should be removed. Unless the
>> documentation is designed to give the version information of for
>> changelog stuff.
>>
>> On Mon, Jun 18, 2018 at 1:19 PM, Vincent Massol <[hidden email]>
>> wrote:
>>> Hi,
>>>
>>> I think we need to start removing old mentions on xwiki.org. It makes
>> it harder to read xwiki pages (as a user has just reported, see
>> https://forum.xwiki.org/t/how-to-increase-active-installs-
>> of-xwiki/3132/6?u=vmassol).
>>>
>>> Also we said we don't support documenting old stuff (we only support doc
>> for LTS, stable and latest).
>>>
>>> For example I just did this:
>>> http://www.xwiki.org/xwiki/bin/view/Documentation/
>> AdminGuide/Installation/InstallationConcludingSteps/?
>> viewer=changes&rev1=11.2&rev2=11.3
>>>
>>> Is that ok with everyone?
>>>
>>> Thanks
>>> -Vincent
>>>
>>
>>
>>
>> --
>> Thomas Mortagne
>>

Reply | Threaded
Open this post in threaded view
|

Re: [Brainstormoing] Removing old "since" from xwiki.org

Ecaterina Moraru (Valica)
Maybe it would be interesting for us to provide this export for version
cycles, at the end of the year, if not for individual versions. But I know
it's a lot of work.

Thanks,
Caty

On Mon, Jun 18, 2018 at 4:52 PM, Vincent Massol <[hidden email]> wrote:

>
>
> > On 18 Jun 2018, at 15:06, Ecaterina Moraru (Valica) <[hidden email]>
> wrote:
> >
> > If we were to export PDFs of documentation at a certain version than I
> > would agree with this.
> > Currently my feeling is that we are deleting information and not all our
> > users are on LTS or recent versions.
>
> Yes but we have to decide between:
> * Make it simpler and nicer for new users coming in and on versions that
> xwiki.org supports
> * Make is less nice for new users but nicer for old users using not
> supported versions of XWiki
>
> So far we’ve decided to not keeping the documentation for old versions of
> XWiki, see https://www.xwiki.org/xwiki/bin/view/Main/Support#
> HSupportedVersions which says "You won't find documentation for old
> versions on this web site”.
>
> > I agree is important to have the most simple and clear documentation, yet
> > it's bad that we don't provide versioned documentation.
> >
> > Also, even cleaning now, it's a task that is very big and the info will
> get
> > deprecated in a year. If the language we use is using present tense,
> users
> > will still be confused 1 year later and still would not know about what
> > version that documentation is talking about. Especially since there is no
> > way we could validate documentation on year release.
> >
> > I don't have a clear solution for this problem.
>
> Me neither and I don’t think there’s a magical solution :)
>
> Note that now that we’ve removed the platform and enterprise wikis and
> moved the main doc under https://www.xwiki.org/xwiki/
> bin/view/Documentation/ it’s slightly easier to copy the documentation:
> we would need to copy this space when we do a release. Note that e.x.o
> would need to be handled too.
>
> But that’s just the technical aspect.
>
> In practice it’s a LOT of work to handle several versions as ElasticSearch
> is doing: https://www.elastic.co/guide/index.html
>
> The work I can imagine:
> * Whenever adding something new, need to decide in which doc version it
> goes. And right now we don’t have merge support in XWiki so it would need
> to be by hand
> * When we do refactorings (so on the latest doc), and we need to merge to
> LTS or Stable we need to find the old place where it was
>
> In any case it would take substantial more time to handle multiple
> versions (not even mentioning multiple languages ;)). And I don’t think we
> have a large enough participating community to allow for this….
>
> <aside>
> If you remember Caty, at some point, we discussed about implementing an
> app for doing this. In short it would be similar to the Release Notes app
> where you can add a new release change item (here it would be a new Doc
> item) and when you do so, you also enter info in the xproperty
> corresponding to the versions that apply to the doc item. Ofc you also
> enter the Category/Subcategories (or tags), etc.
>
> Then you can browse a Categories/Tags, say “Installation” and “MySQL” and
> an XWik version (defaults to latest) and you’ll have a nice LT with all the
> doc items corresponding to that.
>
> Ofc there are problems with this, for ex:
> * coherent doc
> * you must have one item doc per heading (to be fined-grained enough,
> works less well for tutorials types of documents)
> </aside>
>
> Thanks
> -Vincent
>
> > Thanks,
> > Caty
> >
> > On Mon, Jun 18, 2018 at 3:44 PM, Thomas Mortagne <
> [hidden email]>
> > wrote:
> >
> >> Sure, make sense.
> >>
> >> I guess most document useless in >=LTS should be removed. Unless the
> >> documentation is designed to give the version information of for
> >> changelog stuff.
> >>
> >> On Mon, Jun 18, 2018 at 1:19 PM, Vincent Massol <[hidden email]>
> >> wrote:
> >>> Hi,
> >>>
> >>> I think we need to start removing old mentions on xwiki.org. It makes
> >> it harder to read xwiki pages (as a user has just reported, see
> >> https://forum.xwiki.org/t/how-to-increase-active-installs-
> >> of-xwiki/3132/6?u=vmassol).
> >>>
> >>> Also we said we don't support documenting old stuff (we only support
> doc
> >> for LTS, stable and latest).
> >>>
> >>> For example I just did this:
> >>> http://www.xwiki.org/xwiki/bin/view/Documentation/
> >> AdminGuide/Installation/InstallationConcludingSteps/?
> >> viewer=changes&rev1=11.2&rev2=11.3
> >>>
> >>> Is that ok with everyone?
> >>>
> >>> Thanks
> >>> -Vincent
> >>>
> >>
> >>
> >>
> >> --
> >> Thomas Mortagne
> >>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstormoing] Removing old "since" from xwiki.org

Eduard Moraru
I'm personally not a very big fan of deleting information. Providing
support for older versions is about maintaining or adding new documentation
for old versions, something that we clearly don't do. However, IMO, that is
a different thing than actually removing precious documentation for users
that are still on older versions. This would also impact 3rd party support
teams offering support for their clients running older XWiki versions.

Indeed, it would only make sense to have only the latest version of the
documentation if we take snapshots of all the documentation we have (i.e. *.
xwiki.org), when releasing a new version. This would still allow browsing
the old snapshots and getting the documentation state that corresponds to a
particular version, while for us, as developers, it would only mean
worrying about keeping the documentation up to date only for the latest
version.

This strategy should also cover LTS, since after the LTS release (i.e. 9.11
at present time), the LTS documentation should suffer no new feature or
improvements changes, only bugfixes. This means that the LTS documentation
that was archived at its release should not need updating and we would have
no issue with the most recent (dev branch) documentation being very
different.

Yes, I know that in practice (actually for 9.11.x as well) we have ended up
pushing new features into the LTS branch, but we consider this a bad
practice that we should not really consider when discussing this
documentation strategy. Also, should it really be necessary (maybe like for
the case of 9.11.x with Notifications), we could even exceptionally update
some of the archived doc.

This strategy should also cover the stable release, since given the short
(1 month) timespan between releases we won't be needing to make updates on
the documentation of a previously released stable version.

Of course, the biggest question is the scalability of having to save and
store a snapshot of *.xwiki.org and how it would be accessible:
* online XWiki instances running in read only mode (expensive and overkill,
but at least things like livetables will function correctly)
* online static HTML export (might be an interesting option, but livetables
will not function except if they are specially exported as static tables or
something like that -- might be worth pursuing)
* downloadable PDF export (might produce linking issues and no javascript
or livetables support)
* downloadable XAR package (would be hard to use and would require local
dedicated instance to install and read the documentation, but everything
should be functional)

WDYT?

P.S.: I know it's not an easy task (compared to deleting some Since
references), but it's something we are severely lacking (due to the way we
organize our docs) and we are in a high disadvantage over a great number of
projects that clearly version their documentation and inspire confidence to
their users.

Thanks,
Eduard

On Mon, Jun 18, 2018 at 5:13 PM, Ecaterina Moraru (Valica) <
[hidden email]> wrote:

> Maybe it would be interesting for us to provide this export for version
> cycles, at the end of the year, if not for individual versions. But I know
> it's a lot of work.
>
> Thanks,
> Caty
>
> On Mon, Jun 18, 2018 at 4:52 PM, Vincent Massol <[hidden email]>
> wrote:
>
> >
> >
> > > On 18 Jun 2018, at 15:06, Ecaterina Moraru (Valica) <[hidden email]
> >
> > wrote:
> > >
> > > If we were to export PDFs of documentation at a certain version than I
> > > would agree with this.
> > > Currently my feeling is that we are deleting information and not all
> our
> > > users are on LTS or recent versions.
> >
> > Yes but we have to decide between:
> > * Make it simpler and nicer for new users coming in and on versions that
> > xwiki.org supports
> > * Make is less nice for new users but nicer for old users using not
> > supported versions of XWiki
> >
> > So far we’ve decided to not keeping the documentation for old versions of
> > XWiki, see https://www.xwiki.org/xwiki/bin/view/Main/Support#
> > HSupportedVersions which says "You won't find documentation for old
> > versions on this web site”.
> >
> > > I agree is important to have the most simple and clear documentation,
> yet
> > > it's bad that we don't provide versioned documentation.
> > >
> > > Also, even cleaning now, it's a task that is very big and the info will
> > get
> > > deprecated in a year. If the language we use is using present tense,
> > users
> > > will still be confused 1 year later and still would not know about what
> > > version that documentation is talking about. Especially since there is
> no
> > > way we could validate documentation on year release.
> > >
> > > I don't have a clear solution for this problem.
> >
> > Me neither and I don’t think there’s a magical solution :)
> >
> > Note that now that we’ve removed the platform and enterprise wikis and
> > moved the main doc under https://www.xwiki.org/xwiki/
> > bin/view/Documentation/ it’s slightly easier to copy the documentation:
> > we would need to copy this space when we do a release. Note that e.x.o
> > would need to be handled too.
> >
> > But that’s just the technical aspect.
> >
> > In practice it’s a LOT of work to handle several versions as
> ElasticSearch
> > is doing: https://www.elastic.co/guide/index.html
> >
> > The work I can imagine:
> > * Whenever adding something new, need to decide in which doc version it
> > goes. And right now we don’t have merge support in XWiki so it would need
> > to be by hand
> > * When we do refactorings (so on the latest doc), and we need to merge to
> > LTS or Stable we need to find the old place where it was
> >
> > In any case it would take substantial more time to handle multiple
> > versions (not even mentioning multiple languages ;)). And I don’t think
> we
> > have a large enough participating community to allow for this….
> >
> > <aside>
> > If you remember Caty, at some point, we discussed about implementing an
> > app for doing this. In short it would be similar to the Release Notes app
> > where you can add a new release change item (here it would be a new Doc
> > item) and when you do so, you also enter info in the xproperty
> > corresponding to the versions that apply to the doc item. Ofc you also
> > enter the Category/Subcategories (or tags), etc.
> >
> > Then you can browse a Categories/Tags, say “Installation” and “MySQL” and
> > an XWik version (defaults to latest) and you’ll have a nice LT with all
> the
> > doc items corresponding to that.
> >
> > Ofc there are problems with this, for ex:
> > * coherent doc
> > * you must have one item doc per heading (to be fined-grained enough,
> > works less well for tutorials types of documents)
> > </aside>
> >
> > Thanks
> > -Vincent
> >
> > > Thanks,
> > > Caty
> > >
> > > On Mon, Jun 18, 2018 at 3:44 PM, Thomas Mortagne <
> > [hidden email]>
> > > wrote:
> > >
> > >> Sure, make sense.
> > >>
> > >> I guess most document useless in >=LTS should be removed. Unless the
> > >> documentation is designed to give the version information of for
> > >> changelog stuff.
> > >>
> > >> On Mon, Jun 18, 2018 at 1:19 PM, Vincent Massol <[hidden email]>
> > >> wrote:
> > >>> Hi,
> > >>>
> > >>> I think we need to start removing old mentions on xwiki.org. It
> makes
> > >> it harder to read xwiki pages (as a user has just reported, see
> > >> https://forum.xwiki.org/t/how-to-increase-active-installs-
> > >> of-xwiki/3132/6?u=vmassol).
> > >>>
> > >>> Also we said we don't support documenting old stuff (we only support
> > doc
> > >> for LTS, stable and latest).
> > >>>
> > >>> For example I just did this:
> > >>> http://www.xwiki.org/xwiki/bin/view/Documentation/
> > >> AdminGuide/Installation/InstallationConcludingSteps/?
> > >> viewer=changes&rev1=11.2&rev2=11.3
> > >>>
> > >>> Is that ok with everyone?
> > >>>
> > >>> Thanks
> > >>> -Vincent
> > >>>
> > >>
> > >>
> > >>
> > >> --
> > >> Thomas Mortagne
> > >>
> >
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstormoing] Removing old "since" from xwiki.org

vmassol
Administrator
In reply to this post by vmassol
Please note that the original goal here was not to discuss what we would do if we were a large project with lots of developers, who liked to write documentation, etc :)

The goal was:
1) to answer the feedback we got from a reader saying that we have too many distractions when reading xwiki wiki pages and that they break the visual flow and make the pages harder to read, all this in an offer to bring in more users and increase the active installs.
2) to implement what we decided a long time ago, ie. support only 3 branches, see https://www.xwiki.org/xwiki/bin/view/Main/Support#HSupportedVersions

One relatively simple alternative if we really don’t want to remove some information could be:

* Implement a {{backwardCompatibilityMacro/}} wiki macro on xwiki.org that you would use to put information about previous versions of XWiki
* When viewing it, it would be folded by default with some small clickable indicator/icon in the gutter (or somewhere else), which, when clicked, would make it visible. Another option would be a “show backward compat info” toggle somewhere in the page UI.

I still prefer a lot to remove old stuff and to continue our strategy of only supporting 3 branches and to push users to upgrades to those 3 branches because that’s one way of participating to the XWiki  open source project as it makes users test those versions and upgrade.

Thanks
-Vincent

> On 18 Jun 2018, at 13:19, Vincent Massol <[hidden email]> wrote:
>
> Hi,
>
> I think we need to start removing old mentions on xwiki.org. It makes it harder to read xwiki pages (as a user has just reported, see https://forum.xwiki.org/t/how-to-increase-active-installs-of-xwiki/3132/6?u=vmassol).
>
> Also we said we don't support documenting old stuff (we only support doc for LTS, stable and latest).
>
> For example I just did this:
> http://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/Installation/InstallationConcludingSteps/?viewer=changes&rev1=11.2&rev2=11.3 
>
> Is that ok with everyone?
>
> Thanks
> -Vincent
>