<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class="">Marcin,<div class=""><br class=""></div><div class="">Thanks for sketching out the mechanisms we could use to help ensure the quality and accuracy of the documentation. If someone in the community is willing to work on any or all of these items, I will ask the OpenSFS board to cover the costs of any CI/CD cloud services that are needed. I would rather see the expertise of those doing the work targeted at improving Lustre than hosting services available for modest costs.</div><div class=""><br class=""></div><div class="">—Rick</div><div class=""><br class=""><div><blockquote type="cite" class=""><div class="">On Nov 18, 2017, at 2:47 AM, Marcin Dulak <<a href="mailto:marcin.dulak@gmail.com" class="">marcin.dulak@gmail.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div dir="ltr" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><div class="gmail_extra"><br class="Apple-interchange-newline"><br class=""><div class="gmail_quote">On Sat, Nov 18, 2017 at 4:20 AM, Stu Midgley<span class="Apple-converted-space"> </span><span dir="ltr" class=""><<a href="mailto:sdm900@gmail.com" target="_blank" class="">sdm900@gmail.com</a>></span><span class="Apple-converted-space"> </span>wrote:<br class=""><blockquote class="gmail_quote" style="margin: 0px 0px 0px 0.8ex; border-left-width: 1px; border-left-style: solid; border-left-color: rgb(204, 204, 204); padding-left: 1ex;"><div dir="ltr" class=""><div style="font-family: monospace, monospace;" class="">Thank you both for the documentation. I know how hard it is to maintain. </div><div style="font-family: monospace, monospace;" class=""><br class=""></div><div style="font-family: monospace, monospace;" class="">I've asked that all my admin staff to read it - even if some of it doesn't directly apply to our environment.</div><div style="font-family: monospace, monospace;" class=""><br class=""></div><div style="font-family: monospace, monospace;" class="">What we would like is ell organised, comprehensive, accurate and up to date documenation. Most of the time when I dive into the manual, or other online material, I find it isn't quite right (path's slightly wrong or outdated etc). I also have difficulty finding all the information I want in a single location and in a logical fashon. These aren't new issues and blight all documentation, but having the definitive source in a wiki might open it up to more transparency, greater use and thus, ultimately, being kept up to date, even if its by others outside Intel.</div></div></blockquote><div class=""><br class=""></div><div class="">Documentation should be treated in the say way as code, i.e. automatically tested. This is not a new idea <a href="https://en.wikipedia.org/wiki/Software_documentation#Literate_programming" class="">https://en.wikipedia.org/wiki/Software_documentation#Literate_programming</a><br class=""></div><div class="">and with the access to various kinds of virtualization this is feasible now.</div><div class="">There are Python projects (<a href="https://gitlab.com/ase/ase/tree/master/doc/tutorials" class="">https://gitlab.com/ase/ase/tree/master/doc/tutorials</a>), that make use of this idea thanks to <a href="http://www.sphinx-doc.org/" class="">http://www.sphinx-doc.org</a><span class="Apple-converted-space"> </span>which allows one to execute embedded Python commands</div><div class="">during the process of building the documentation in html or pdf formats out of rst (restructured text) files.</div><div class="">There is a system that stores LFS (Linux from scratch) in an xml format for extraction to be executed<span class="Apple-converted-space"> </span><a href="http://www.linuxfromscratch.org/alfs/" class="">http://www.linuxfromscratch.org/alfs/</a> <a href="https://github.com/ojab/jhalfs" class="">https://github.com/ojab/jhalfs</a><span class="Apple-converted-space"> </span>but it seems not to be under a continuous automatic testing.</div><div class="">However, projects like <a href="https://docs.openstack.org/install-guide/" class="">https://docs.openstack.org/install-guide/</a><span class="Apple-converted-space"> </span>suprisingly do not use this idea and it takes months to correct a small inconsistency in the documentation <a href="https://bugs.launchpad.net/keystone/+bug/1698455" class="">https://bugs.launchpad.net/keystone/+bug/1698455</a></div><div class=""><br class=""></div><div class="">It is not very difficult to create a virtual setup consisting of several lustre servers in an unattended way (<a href="https://github.com/marcindulak/vagrant-lustre-tutorial-centos6" class="">https://github.com/marcindulak/vagrant-lustre-tutorial-centos6</a>) and use that</div><div class="">to test the lustre documentation.</div><div class="">An alternative to making the lustre documentation executable would be to abstract the basics of lustre using a supported configuration management system (is there any progress about <span style="color: rgb(0, 102, 33); font-size: 14px; white-space: nowrap;" class=""><a href="https://www.youtube.com/watch?v=WX00LQLYf2w" class="">https://www.youtube.com/watch?v=WX00LQLYf2w</a><span class="Apple-converted-space"> </span>?) </span>and test that using the standard CI tools.</div><div class=""><br class=""></div><div class="">Cheers</div><div class=""><br class=""></div><div class="">Marcin</div><div class=""> </div><blockquote class="gmail_quote" style="margin: 0px 0px 0px 0.8ex; border-left-width: 1px; border-left-style: solid; border-left-color: rgb(204, 204, 204); padding-left: 1ex;"><div dir="ltr" class=""><div style="font-family: monospace, monospace;" class=""><br class=""></div><div style="font-family: monospace, monospace;" class="">I'd also like a section where people can post their experiences and solutions. For example, in recent times, we have battled bad interactions with ZFS+lustre which lead to poor performance and ZFS corruption. While we have now tuned both lustre and zfs and the bugs have mostly been fixed, the learnings, trouble shooting methods etc. should be preserved and might assist others in the future diagnose tricky problems.</div></div></blockquote><div class=""><br class=""></div><div class=""> </div><blockquote class="gmail_quote" style="margin: 0px 0px 0px 0.8ex; border-left-width: 1px; border-left-style: solid; border-left-color: rgb(204, 204, 204); padding-left: 1ex;"><div dir="ltr" class=""><div style="font-family: monospace, monospace;" class=""><br class=""></div><div style="font-family: monospace, monospace;" class="">That's my 5c.</div><div style="font-family: monospace, monospace;" class=""><br class=""></div><div style="font-family: monospace, monospace;" class=""><br class=""></div></div><div class="gmail_extra"><br class=""><div class="gmail_quote">On Sat, Nov 18, 2017 at 6:03 AM, Dilger, Andreas<span class="Apple-converted-space"> </span><span dir="ltr" class=""><<a href="mailto:andreas.dilger@intel.com" target="_blank" class="">andreas.dilger@intel.com</a>></span><span class="Apple-converted-space"> </span>wrote:<br class=""><blockquote class="gmail_quote" style="margin: 0px 0px 0px 0.8ex; border-left-width: 1px; border-left-style: solid; border-left-color: rgb(204, 204, 204); padding-left: 1ex;">On Nov 16, 2017, at 22:41, Cowe, Malcolm J <<a href="mailto:malcolm.j.cowe@intel.com" target="_blank" class="">malcolm.j.cowe@intel.com</a>> wrote:<br class="">><br class="">> I am pleased to announce the availability of a new systems administration guide for the Lustre file system, which has been published to<span class="Apple-converted-space"> </span><a href="http://wiki.lustre.org/" rel="noreferrer" target="_blank" class="">wiki.lustre.org</a>. The content can be accessed directly from the front page of the wiki, or from the following URL:<br class="">><br class="">><span class="Apple-converted-space"> </span><a href="http://wiki.lustre.org/Category:Lustre_Systems_Administration" rel="noreferrer" target="_blank" class="">http://wiki.lustre.org/Categor<wbr class="">y:Lustre_Systems_Administratio<wbr class="">n</a><br class="">><br class="">> The guide is intended to provide comprehensive instructions for the installation and configuration of production-ready Lustre storage clusters. Topics covered:<br class="">><br class="">> • Introduction to Lustre<br class="">> • Lustre File System Components<br class="">> • Lustre Software Installation<br class="">> • Lustre Networking (LNet)<br class="">> • LNet Router Configuration<br class="">> • Lustre Object Storage Devices (OSDs)<br class="">> • Creating Lustre File System Services<br class="">> • Mounting a Lustre File System on Client Nodes<br class="">> • Starting and Stopping Lustre Services<br class="">> • Lustre High Availability<br class="">><br class="">> Refer to the front page of the guide for the complete table of contents.<br class=""><br class="">Malcolm,<br class="">thanks so much for your work on this. It is definitely improving the<br class="">state of the documentation available today.<br class=""><br class="">I was wondering if people have an opinion on whether we should remove<br class="">some/all of the administration content from the Lustre Operations Manual,<br class="">and make that more of a reference manual that contains details of<br class="">commands, architecture, features, etc. as a second-level reference from<br class="">the wiki admin guide?<br class=""><br class="">For that matter, should we export the XML Manual into the wiki and<br class="">leave it there? We'd have to make sure that the wiki is being indexed<br class="">by Google for easier searching before we could do that.<br class=""><br class="">Cheers, Andreas<br class=""><br class="">> In addition, for people who are new to Lustre, there is a high-level introduction to Lustre concepts, available as a PDF download:<br class="">><br class="">><span class="Apple-converted-space"> </span><a href="http://wiki.lustre.org/images/6/64/LustreArchitecture-v4.pdf" rel="noreferrer" target="_blank" class="">http://wiki.lustre.org/images/<wbr class="">6/64/LustreArchitecture-v4.pdf</a><br class="">><br class="">><br class="">> Malcolm Cowe<br class="">> High Performance Data Division<br class="">><br class="">> Intel Corporation |<span class="Apple-converted-space"> </span><a href="http://www.intel.com/" rel="noreferrer" target="_blank" class="">www.intel.com</a><br class="">><br class="">> ______________________________<wbr class="">_________________<br class="">> lustre-discuss mailing list<br class="">><span class="Apple-converted-space"> </span><a href="mailto:lustre-discuss@lists.lustre.org" target="_blank" class="">lustre-discuss@lists.lustre.or<wbr class="">g</a><br class="">><span class="Apple-converted-space"> </span><a href="http://lists.lustre.org/listinfo.cgi/lustre-discuss-lustre.org" rel="noreferrer" target="_blank" class="">http://lists.lustre.org/listin<wbr class="">fo.cgi/lustre-discuss-lustre.<wbr class="">org</a><br class=""><br class="">Cheers, Andreas<br class="">--<br class="">Andreas Dilger<br class="">Lustre Principal Architect<br class="">Intel Corporation<br class=""><br class=""><br class=""><br class=""><br class=""><br class=""><br class=""><br class="">______________________________<wbr class="">_________________<br class="">lustre-discuss mailing list<br class=""><a href="mailto:lustre-discuss@lists.lustre.org" target="_blank" class="">lustre-discuss@lists.lustre.or<wbr class="">g</a><br class=""><a href="http://lists.lustre.org/listinfo.cgi/lustre-discuss-lustre.org" rel="noreferrer" target="_blank" class="">http://lists.lustre.org/listin<wbr class="">fo.cgi/lustre-discuss-lustre.<wbr class="">org</a><span class="gmail-HOEnZb"><font color="#888888" class=""><br class=""></font></span></blockquote></div><span class="gmail-HOEnZb"><font color="#888888" class=""><br class=""><br clear="all" class=""><div class=""><br class=""></div>--<span class="Apple-converted-space"> </span><br class=""><div class="gmail-m_2515768125150461237gmail_signature"><div dir="ltr" class=""><div class=""><font face="monospace, monospace" class="">Dr Stuart Midgley<br class=""><a href="mailto:sdm900@gmail.com" target="_blank" class="">sdm900@gmail.com</a></font></div></div></div></font></span></div><br class="">______________________________<wbr class="">_________________<br class="">lustre-discuss mailing list<br class=""><a href="mailto:lustre-discuss@lists.lustre.org" class="">lustre-discuss@lists.lustre.<wbr class="">org</a><br class=""><a href="http://lists.lustre.org/listinfo.cgi/lustre-discuss-lustre.org" rel="noreferrer" target="_blank" class="">http://lists.lustre.org/<wbr class="">listinfo.cgi/lustre-discuss-<wbr class="">lustre.org</a><br class=""><br class=""></blockquote></div><br class=""></div></div><span style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">_______________________________________________</span><br style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><span style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; float: none; display: inline !important;" class="">lustre-discuss mailing list</span><br style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><a href="mailto:lustre-discuss@lists.lustre.org" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px;" class="">lustre-discuss@lists.lustre.org</a><br style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px;" class=""><a href="http://lists.lustre.org/listinfo.cgi/lustre-discuss-lustre.org" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px;" class="">http://lists.lustre.org/listinfo.cgi/lustre-discuss-lustre.org</a></div></blockquote></div><br class=""></div></body></html>