[Gluster-devel] Documentation expectations for 3.5 release

[Justin Clift]

Hi all,

These are the features in Gluster 3.5 still needing documentation:

 * AFR CLI enhancements
 * Exposing Volume Capabilities <- only if this made it in, which I can't see atm
 * File Snapshots in GlusterFS
 * gfid-access
 * On-Wire Compression/Decompression
 * Preventing NFS restart on volume change
 * Quota Scalability
 * readdir-ahead
 * zerofill API for GlusterFS
 * Brick Failure Detection
 * Disk Encryption
 * Changelog based parallel geo-replication
 * Improved block device translator
 * Remove brick CLI change
 * RDMA-connection manager (RDMA-CM)
 * Support for NUFA translator
 * Distributed Geo-Replication

These are the features added in Gluster 3.4, still needing documentation:

 * Write Once Read Many (WORM) volume
 * BD Xlator - Block Device translator
 * Duplicate Request Cache (DRC)
 * Server-Quorum
 * Libgfapi
 * Eager locking
 * oVirt 3.2 integration
 * qemu 1.3 - libgfapi integration
 * Access Control List - Version 3 support for Gluster NFS


All of the required documentation is *end user focused*, which includes
three parts:

  a) Description of what a feature does, so a user knows if it's something
     they'd want to use or try

  b) Exact steps on setting it up, and full list of parameters that can affect
     it.  For example:

       * CLI parameters (if it has them)
       * Volume options/parameters (if it has them)
       * Dependencies, (eg on other features, external programs,
         etc)

  c) A fully worked example.  Step by step commands with comments are optimal.

A good way to start is by doing the setup/configuration for the feature in your
local environment, starting from a new, un-configured installation. Ensure your
terminal program has a lot of scroll back buffer available. :)

After the environment is fully configured, cut-n-paste the scroll back buffer
into a text mode document editor somewhere (or an etherpad).  Then go through
it, removing everything except the needed commands and any useful output.

Then go through it a 2nd time, adding line feeds and headings, spacing things
out visually for clarity, and adding comments to describe what's going on and
why it's being done.

This becomes the c) in the list above.  With that in place, it's generally
pretty straight forward to next make the b) part, and then finishing off with
a full feature description appropriate for end users (if it hasn't
spontaneously come to mind already).

The text format we're using is AsciiDoc.  Quick Reference here:

  http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

:)

Regards and best wishes,

Justin Clift

--
Open Source and Standards @ Red Hat

twitter.com/realjustinclift