gluster-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Gluster-devel] Documentation expectations for 3.5 release


From: Vijay Bellur
Subject: Re: [Gluster-devel] Documentation expectations for 3.5 release
Date: Tue, 15 Apr 2014 00:12:22 -0700
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:24.0) Gecko/20100101 Thunderbird/24.4.0

Thank you all for your efforts in arriving at better user documentation.

Since we did not do a thorough job of blocking patches that did not have adequate updates to the admin guide in the run upto 3.5.0, it certainly seems difficult to get all admin-guide content ready in short order. Hence I think it might be prudent to treat the documentation bugs as blockers for 3.5.1. There is documentation for most features mentioned in the bugs in some form (git commit messages, feature pages, blog posts) etc.It might be a good idea to consolidate all such links in one place.

My preference would be to release 3.5.0 and ensure that our admin guide is ready in terms of content by 3.5.1.

Regards,
Vijay

On 04/11/2014 06:40 AM, John Mark Walker wrote:
Thank you, guys, for taking this on. The community will greatly benefit from 
this effort.

-JM


----- Original Message -----
On Thu, Apr 10, 2014 at 11:47:08PM +0530, Lalatendu Mohanty wrote:
On 04/10/2014 11:20 PM, Justin Clift wrote:
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).

Here is the documentation about "how to send documentation patch" :
http://www.gluster.org/community/documentation/index.php/Submitting_Documentation_Patches

Lala and I have been busy filing bugs for all of the features that are
listed in the email below as having missing documentation:
- https://bugzilla.redhat.com/showdependencytree.cgi?id=1049981

All the bugs that are *not* in POST or MODIFIED state need to file
patches. The ones that are in POST could probably benefit from reviews
in Gerrit (see the respective bug for details).

Note that these bugs need patches submitted against the release-3.5
branch, as well as the master branch. We do not want documentation lost
with future releases.

If you have any questions, please let us know by replying to this email,
or talk to us in #gluster-dev on Freenode.

Thanks,
Niels



+ 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

--




reply via email to

[Prev in Thread] Current Thread [Next in Thread]