[lustre-discuss] Announce: Lustre Systems Administration Guide

[DEGREMONT Aurelien]

Hello

My recommendation would be to go for something like Documentation-as-a-code.
It is now very easy to deploy an infrastructure to automatically 
generate nice looking HTML and PDF versions of a rst or markdown 
documentation thanks to readthedocs.io

readthedocs.io uses Sphinx as backend, likewise kernel.org 
(https://www.kernel.org/doc/html/v4.11/doc-guide/sphinx.html)

A github project could be easy plugged to readthedocs, but you could use 
your own hooks.

If you use GitHub to store your source code, you can easily edit the 
documentation source code and create a pull request. I know this is not 
in line with Gerrit usage, but this is an interesting workflow.

I really think we should really uses such technologies which produce 
very nice looking documentation, which could be easily exports, 
versionned and coupled with a git repository. See how kernel.org uses it.

MediaWiki is not a good fit for doc manual like Lustre one. Not easy to 
browse, not easy to export.


My 2 cents

Aurélien

Le 17/11/2017 à 23:03, Dilger, Andreas a écrit :
> On Nov 16, 2017, at 22:41, Cowe, Malcolm J <malcolm.j.cowe at intel.com> wrote:
>> I am pleased to announce the availability of a new systems administration guide for the Lustre file system, which has been published to wiki.lustre.org. The content can be accessed directly from the front page of the wiki, or from the following URL:
>>   
>> http://wiki.lustre.org/Category:Lustre_Systems_Administration
>>   
>> The guide is intended to provide comprehensive instructions for the installation and configuration of production-ready Lustre storage clusters. Topics covered:
>>   
>> 	• Introduction to Lustre
>> 	• Lustre File System Components
>> 	• Lustre Software Installation
>> 	• Lustre Networking (LNet)
>> 	• LNet Router Configuration
>> 	• Lustre Object Storage Devices (OSDs)
>> 	• Creating Lustre File System Services
>> 	• Mounting a Lustre File System on Client Nodes
>> 	• Starting and Stopping Lustre Services
>> 	• Lustre High Availability
>>   
>> Refer to the front page of the guide for the complete table of contents.
> Malcolm,
> thanks so much for your work on this.  It is definitely improving the
> state of the documentation available today.
>
> I was wondering if people have an opinion on whether we should remove
> some/all of the administration content from the Lustre Operations Manual,
> and make that more of a reference manual that contains details of
> commands, architecture, features, etc. as a second-level reference from
> the wiki admin guide?
>
> For that matter, should we export the XML Manual into the wiki and
> leave it there?  We'd have to make sure that the wiki is being indexed
> by Google for easier searching before we could do that.
>
> Cheers, Andreas
>
>> In addition, for people who are new to Lustre, there is a high-level introduction to Lustre concepts, available as a PDF download:
>>   
>> http://wiki.lustre.org/images/6/64/LustreArchitecture-v4.pdf
>>   
>>   
>> Malcolm Cowe
>> High Performance Data Division
>>   
>> Intel Corporation | www.intel.com
>>   
>> _______________________________________________
>> lustre-discuss mailing list
>> lustre-discuss at lists.lustre.org
>> http://lists.lustre.org/listinfo.cgi/lustre-discuss-lustre.org
> Cheers, Andreas
> --
> Andreas Dilger
> Lustre Principal Architect
> Intel Corporation
>
>
>
>
>
>
>
> _______________________________________________
> lustre-discuss mailing list
> lustre-discuss at lists.lustre.org
> http://lists.lustre.org/listinfo.cgi/lustre-discuss-lustre.org