https://jira.whamcloud.com This file is an XML representation of an issue en-us 9.4.14 940014 05-12-2023 https://jira.whamcloud.com/browse/LUDOC-47 Lustre Documentation <p>Currently the links on <a href="http://wiki.whamcloud.com/display/PUB/Documentation" class="external-link" target="_blank" rel="nofollow noopener">http://wiki.whamcloud.com/display/PUB/Documentation</a> point to the master branch's latest build of the documentation (and to some older versions of the manual).</p> <p>Two problems: </p> <ul> <li>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</li> <li>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.</li> </ul> <p>Suggestions:</p> <ul> <li>The top link that newcomers naturally click on the documentation page should point to the latest release version, not master.</li> <li>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).</li> <li>As part of the Lustre release process, a manual snapshot should be taken and used to update the wiki page.</li> </ul> LUDOC-47

Documentation wiki page should provide release versions of manual for download

Improvement Minor Closed Won't Fix Richard Henwood John Spray QInfrastructure Tue, 21 Feb 2012 11:33:40 +0000 Tue, 8 Oct 2013 18:20:24 +0000 Tue, 8 Oct 2013 18:20:19 +0000 0 2 <p>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.</p> <p>Cliff feels this is important to have in place before LUG.</p> <p>I read this as two issues:</p> <p>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.</p> <p>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.</p> <p>Two issues were unearthed during the discussion of branches:</p> <ul> <li>Additional resources to support multiple branches could not be identified. Corrections would need to be made on all branches. This requires more effort.</li> <li>Lustre provides interoperability between client and server versions. I was not satisfied that a Manual for individual Lustre releases could conveniently accommodate this information.</li> </ul> <p>What do you think?</p> <p>Issue #1 above is covered in <a href="https://jira.hpdd.intel.com/browse/IT-220" class="external-link" target="_blank" rel="nofollow noopener">https://jira.hpdd.intel.com/browse/IT-220</a>. We will use this ticket to track issue #2 going forward.</p> <p>I have received continued interest and feedback on this ticket out-of-band.</p> <p>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.</p> <p>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:</p> <p><a href="https://wiki.hpdd.intel.com/display/PUB/Guidance+for+Manual+reviewers#GuidanceforManualreviewers-Lustreversionspecifichints" class="external-link" target="_blank" rel="nofollow noopener">https://wiki.hpdd.intel.com/display/PUB/Guidance+for+Manual+reviewers#GuidanceforManualreviewers-Lustreversionspecifichints</a>.</p> Business Value 30.0 Development Rank 1|hzvl0f: Rank (Obsolete) 7165