xfs
[Top] [All Lists]

documentation framework [was Re: relationship of nested stripe sizes, wa

To: Stan Hoeppner <stan@xxxxxxxxxxxxxxxxx>
Subject: documentation framework [was Re: relationship of nested stripe sizes, was: Question regarding XFS on LVM over hardware RAID.]
From: Dave Chinner <david@xxxxxxxxxxxxx>
Date: Tue, 4 Feb 2014 18:06:46 +1100
Cc: xfs <xfs@xxxxxxxxxxx>
Delivered-to: xfs@xxxxxxxxxxx
In-reply-to: <20140203215411.GS13997@dastard>
References: <7A732267-B34F-4286-9B49-3AF8767C0B89@xxxxxxxxxxxxxxxxx> <52ED4143.6090303@xxxxxxxxxxxxxxxxx> <EDBD7355-F1EC-4773-9138-CA864CB2E84B@xxxxxxxxxxxxxxxxx> <52ED6AAF.6030703@xxxxxxxxxxxxxxxxx> <98961D3F-769D-44A9-98A8-FC7867893138@xxxxxxxxxxxxxxxxx> <20140202213030.GQ2212@dastard> <52EF1D76.6070302@xxxxxxxxxxxxxxxxx> <20140203052415.GQ13997@dastard> <52EF6301.5040406@xxxxxxxxxxxxxxxxx> <20140203215411.GS13997@dastard>
User-agent: Mutt/1.5.21 (2010-09-15)
On Tue, Feb 04, 2014 at 08:54:11AM +1100, Dave Chinner wrote:
> On Mon, Feb 03, 2014 at 03:36:01AM -0600, Stan Hoeppner wrote:
> > On 2/2/2014 11:24 PM, Dave Chinner wrote:
> > > On Sun, Feb 02, 2014 at 10:39:18PM -0600, Stan Hoeppner wrote:
> > >> On 2/2/2014 3:30 PM, Dave Chinner wrote:
> > ...
> > >>> And that is why this is a perfect example of what I'd like to see
> > >>> people writing documentation for.
> > >>>
> > >>> http://oss.sgi.com/archives/xfs/2013-12/msg00588.html
> > >>>
> > >>> This is not the first time we've had this nested RAID discussion,
> > >>> nor will it be the last. However, being able to point ot a web page
> > >>> or or documentation makes it a whole lot easier.....
> > >>>
> > >>> Stan - any chance you might be able to spare an hour a week to write
> > >>> something about optimal RAID storage configuration for XFS?
> > >>
> > >> I could do more, probably rather quickly.  What kind of scope, format,
> > >> style?  Should this be structured as reference manual style
> > >> documentation, FAQ, blog??  I'm leaning more towards reference style.
> > > 
> > > Agreed - reference style is probably best. As for format style, I'm
> > > tending towards a simple, text editor friendly markup like asciidoc.
> > > From there we can use it to generate PDFs, wiki documentation, etc
> > > and so make it available in whatever format is convenient.
> > 
> > Works for me, I'm a plain text kinda guy.
> 
> Ok, I'll put together a basic repository and build framework for us
> to work from.

Stan, run:

$ git clone git://oss.sgi.com/xfs/xfs-documentation

to get a tree that contains the framework for building asciidoc
files into html and pdf format. Note that you can't find it from
gitweb of oss.sgi.com yet because I don't have permissions to add it
to the project list, but you can browse it directly from:

http://oss.sgi.com/cgi-bin/gitweb.cgi/xfs/xfs-documentation


I've attached the pdf output of the document I quickly converted
from text to asciidoc format so you can get an idea of how easy it
is to convert plain txt to asciidoc, and how good the output from
just using defaults and simple markup is.

A good cheat sheet for asciidoc markup can be found here:

http://powerman.name/doc/asciidoc

Time to start learning how to use guilt and sending patches. ;)

FWIW, where do we want to locate your new document? It is end
user/admin documentation, so perhaps a new user/ subdirectory to
indicate the target of the documentation?

Cheers,

Dave.
-- 
Dave Chinner
david@xxxxxxxxxxxxx

Attachment: xfs-delayed-logging-design.pdf
Description: Adobe PDF document

<Prev in Thread] Current Thread [Next in Thread>