[Gluster-devel] Documentation expectations for 3.5 release

[Justin Clift]

Note, the docs go in the /doc directory in the git repo, both 3.5 and
master branches. ;)

When submitting patches to gerrit, feel free to reuse the bug-xxxx
branch that was used for the code submission, or even use the 3.5.0
tracker bug (1049981).

+ Justin

On 10/04/2014, at 6:21 PM, Justin Clift wrote:
> 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
> 
> 
> _______________________________________________
> Gluster-devel mailing list
> Gluster-devel at nongnu.org
> https://lists.nongnu.org/mailman/listinfo/gluster-devel

--
Open Source and Standards @ Red Hat

twitter.com/realjustinclift