[Gluster-devel] Documentation expectations for 3.5 release

[Niels de Vos]

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
> >>
> >>--
> >>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
> >
> >
> >_______________________________________________
> >Gluster-devel mailing list
> >Gluster-devel at nongnu.org
> >https://lists.nongnu.org/mailman/listinfo/gluster-devel
> 
> 
> _______________________________________________
> Gluster-devel mailing list
> Gluster-devel at nongnu.org
> https://lists.nongnu.org/mailman/listinfo/gluster-devel

-- 
Niels de Vos
Sr. Software Maintenance Engineer
Support Engineering Group
Red Hat Global Support Services