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 <[email protected]> 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 <[email protected]> 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

On 18 Jun 2018, at 15:06, Ecaterina Moraru (Valica) <[email protected]> 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 <[email protected]> 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 <[email protected]> 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

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) < [email protected]> 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 <[email protected]> wrote:

...

...

On 18 Jun 2018, at 15:06, Ecaterina Moraru (Valica) <[email protected]

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 < [email protected]> 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 <[email protected]> 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