21 Jun
2018
21 Jun
'18
1:59 p.m.
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) <
valicac(a)gmail.com> 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 <vincent(a)massol.net>
wrote:
our
yet
no
ElasticSearch
On 18 Jun 2018, at 15:06, Ecaterina Moraru
(Valica) <valicac(a)gmail.com
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 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, 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 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 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
makes
Thanks,
Caty
On Mon, Jun 18, 2018 at 3:44 PM, Thomas Mortagne <
thomas.mortagne(a)xwiki.com>
> 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 <vincent(a)massol.net>
>> wrote:
>>> Hi,
>>>
>>> I think we need to start removing old mentions on xwiki.org. It > 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
>