[Gluster-devel] Documentation expectations for 3.5 release

Tue Apr 15 15:04:41 UTC 2014

Since 3.5 is a feature release and we have a stable 3.4 I think blocking for documentation is quite sensible. Documentation is the #1 feature request from the community. 

On April 15, 2014 12:12:22 AM PDT, Vijay Bellur <vbellur at redhat.com> wrote:
>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
>>>>>>
>>>>>> --
>
>
>_______________________________________________
>Gluster-devel mailing list
>Gluster-devel at nongnu.org
>https://lists.nongnu.org/mailman/listinfo/gluster-devel

-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://supercolony.gluster.org/pipermail/gluster-devel/attachments/20140415/ee926f10/attachment-0001.html>