[LUDOC-47] Documentation wiki page should provide release versions of manual for download

• Status: Closed
• Project: Lustre Documentation
• Type: Improvement
• Priority: Minor
• Reporter: John Spray (Inactive)
• Assignee: Richard Henwood (Inactive)
• Resolution: Won't Fix
• Labels: QInfrastructure
• Business Value: 30

Description

Currently the links on http://wiki.whamcloud.com/display/PUB/Documentation point to the master branch's latest build of the documentation (and to some older versions of the manual).

Two problems:

• When jenkins is down, people who want to read about Lustre get a broken link when they try to read the manual from the wiki
• It's hard for people to find the version of the manual that goes with the release they're using, once master has moved past that release.

Suggestions:

• The top link that newcomers naturally click on the documentation page should point to the latest release version, not master.
• The artifacts used for release versions of the manual should be put somewhere reliable like downloads.whamcloud.com (unless jenkins has got a more reliable internet connection by the time this ticket is actioned).
• As part of the Lustre release process, a manual snapshot should be taken and used to update the wiki page.

Comments

[John Spray (Inactive)]

Note: this ticket came from some real-life feedback from an external person who was interested in learning more about Lustre and had trouble downloading the manual.

[Linda Bebernes (Inactive)]

Cliff feels this is important to have in place before LUG.

[Richard Henwood (Inactive)]

I read this as two issues:

1. Make sure the Manual is available even when build.whamcloud.com is down. I've been exploring this with Peter and I too would like to see this completed soon.

2. Separate Manuals for each Lustre release. This topic has been discussed informally and I believe there was agreement that practically a branch for code releases (like we do the code) is required.

Two issues were unearthed during the discussion of branches:

• Additional resources to support multiple branches could not be identified. Corrections would need to be made on all branches. This requires more effort.
• Lustre provides interoperability between client and server versions. I was not satisfied that a Manual for individual Lustre releases could conveniently accommodate this information.

What do you think?

[Linda Bebernes (Inactive)]

Issue #1 above is covered in https://jira.hpdd.intel.com/browse/IT-220. We will use this ticket to track issue #2 going forward.

[Richard Henwood (Inactive)]

I have received continued interest and feedback on this ticket out-of-band.

Versioned manuals are reasonable in my opinion - and more importantly - drives towards an important milestone for the manual: achieving a 'release'. I'm pleased to report that there is effort on going to both improve the quality of the manual and ensure the most recent features are documented for users and administrators.

[Richard Henwood (Inactive)]

We now have a method that means we can move forward and in future may create versions. This method uses a 'condition' attribute in relevant sections and is documented here:

https://wiki.hpdd.intel.com/display/PUB/Guidance+for+Manual+reviewers#GuidanceforManualreviewers-Lustreversionspecifichints.