This topic is about how to present documentation when there are UI or feature changes across versions, more specifically deciding if the documentation should be written from the perspective of the LTS version or from the perspective of the latest version.
Proposal 19: Perspective of the Documentation
Option 1
Document the text and UI for the LTS version and then add some {{version since="..."}} macro to show how it looks for the latest version.
Pros:
Users might not be yet on the latest version, so starting from the LTS shows the version that many people still use.
Cons:
When the changes from the latest version will reflect also in the LTS version, changes are required to use the version macro with the before parameter.
For example, the LTS is 16.10.11 and the sentence: "Some inconsistencies of wording were solved {{version since="17.8.0, 17.4.5, 16.10.12"}} and the UI displays "Language." is added to a documentation page. When 16.10.12 becomes the LTS, the sentence needs to become "The UI displays "Language", but {{version before="16.10.12"}} it displayed "Locale".
Option 2
Document the text and UI for the latest version and then add some {{version before="..."}} macro to show how it looks for the LTS.
Pros:
It needs less work because you don’t have to make other changes when the changes from the latest version are brought to the LTS version.
It pushes users to the latest version.
We (@vmassol, @paulinebessoles and myself) prefer option 2 for the pros listed above. Once an agreement is made, this proposal will be moved to the Documentation Guide (that is being refactored at the moment).
+1 for option 2. Personally when developing I work on a latest instance instead of a LTS, and I believe it’s the case for most devs (except when solving LTS specific bugs, which happens rarely ). Because of that, I think about what I’m developing from a latest perspective and it feels more natural to write its doc with option 2.
Thx Lucas for the feedback. Note that the goal of the doc is not to make dev’s life easier but to have what’s best for users/readers even if it’s harder for us devs. In any case I also agree with 2 but for these reasons:
show first the latest and most recent features
Push users to use latest versions and to provide feedback (they get XWiki for free and it’s a way to contribute by testing latest versions).
It’s a bit more complex to document though since it forces us to think about how different the LTS is vs the new changes and might need installing the LTS to take screenshots. So more work.
Note that until now we’ve documented using option 1. If it’s agreed it’s going to be a shift.
I understand outdated versions aren’t supported and we don’t want to have to maintain documentation for it. But I do think it would be nice to have access to old documentation.
It would also have the benefit of making the documentation clearer, as the reader wouldn’t have to mentally filter out the irrelevant information.
I have the example of docs.python.org in mind, I’m sure there are many similarly structured documentations.
I guess we could re-assess the topic if enough people think it’s an interesting topic.
The subjects to answer:
It means that whenever we release a version of XWiki we need to copy the full doc to a new space. We release about 12 times per year for XS, and hundreds of times for extensions. That’s a lot of new docs per year… probably like several thousands new pages every year… Imagine after 20 years…
This could be solved by only supporting the LTS cycle branch and the current stable releases, ie deleting the older spaces…
Add more here
The downsides:
When we improve the doc, we only improve it for the last version. Right now we improve it for all supported versions.
It’s really hard (almost impossible) for readers to understand what has changed. They’d need to visually compare the different versions to find out the differences.
My opinion is that it’s less nice for readers overall and more work for us. If we had lots of changes it might make sense but I don’t think we have such huge number of changes since the last Cycle LTS that it makes the pages too hard to read.
At the time, you suggested having an html export archive of the docs. Has this ever been implemented?
I think it’s an interesting idea and would address your first subject to answer.
Maybe we should stick to release notes for highlighting differences.
If it’s a documentation only difference, such as a new recommendation, maybe it would make sense for it to also appear in the release notes anyway?
It’s true that only keeping the changes since the last cycle LTS reduces the number of changes significantly, but then we’d lose the knowledge about old XWiki versions, wouldn’t we?
Upgrading can sometime take time and I don’t think it’s fair to expect all users to follow the cycle exactly, which brings us back to the html exports question.
No, and I don’t know if it works well enough. There might be too many pages to export. Also it means selecting what to export which isn’t easy (it’s relatively easy for the main wiki for which we could only export the Documentation space, but for the exo wiki, we would need to export all bundled extensions - this could be scripted but requires some work). To be tested if we want to go in that direction. IMO, we won’t get something satisfying since it’s not the goal of the HTML export.
I think the proposal needs to be modified a little:
Use “before” when it’s a change from something that existed
Use “since” when it’s something new that didn’t exist before
The rationale is that without the since for new features, the reader cannot know if it applies to their version or not (they may be on the LTS for ex).
Thanks for the feedback! The status of this proposal: Vincent, Pauline, Eleni, Lucas, Gabriel: +1 for option 2 (that the main perpesctive of the doc must be the latest version). I updated the doc guide accrodingly, including Vincent’s mention that the before parameter can’t be removed, since it’s needed when new features are added.
). Because of that, I think about what I’m developing from a 
but to have what’s best for users/readers even if it’s harder for us devs. In any case I also agree with 2 but for these reasons: