[Gluster-devel] GlusterFS Documentation Improvements - An Update

[Humble Devassy Chirammal]

Hello all,

The GlusterFS documentation team is constantly working to improve the
quality, findability, and usefulness of its documentation. Our goal is to
increase community contribution, remove barriers that discourage
contribution and give you the help you need, when and where you need it. As
part of this strategy, we’ve just rolled out the revamped GlusterFS
Documentation: gluster.readthedocs.org

We started by curating content from various sources including gluster.org
static HTML documentation, various blog posts and the Community wiki. We
used readthedocs service to host the documentation and mkdocs to convert
the Markdown source files to HTML pages. We also put our thought into
classifying the documentation based on their content:


   - Quick Start Guide : A headstart guide for the beginners.


   - Installation Guide : Step by step instructions to install GlusterFS.


   - Administration Guide : Container for for all administrative actions.


   - Developer Guide : Container for all development related aspects.


   - Upgrade Guide : Contains guides to upgrade from older versions of
   GlusterFS.


   - Features : Container for all the features of GlusterFS introduced in
   various versions.


   - GlusterFS Tools : Contains information about the tools used in
   GlusterFS.


   - Troubleshooting Guide : Container for basic troubleshooting and
   debugging guides.


   - Images : Container for images (in .jpg or .png format) that are
   present inline the documentation pages.


Doing so, we gain these benefits:


   - Version based browsable documentation


   - More targeted content


   - Less duplication


   - Faster updates


Whats changing for community members?

A very simplified contribution workflow.

- How to Contribute?

Contributing to the documentation requires a github account. To edit on
github, fork the repository (see top-right of the screen, under your
username). You will then be able to make changes easily. Once done, you can
create a pull request and get the changes reviewed and merged into the
official repository.
With this simplified workflow, the documentation is no longer maintained in
gluster/glusterfs/docs directory but it has a new elevated status in the
form of a new project: gluster/glusterdocs (
https://github.com/gluster/glusterdocs) and currently this project is being
maintained by Anjana Sriram, Shravan and Humble.

- What to Contribute

Really, anything that you think has value to the GlusterFS developer
community. While reading the docs you might find something incorrect or
outdated. Fix it! Or maybe you have an idea for a tutorial, or for a topic
that isn’t covered to your satisfaction. Create a new page and write it up!

Whats Next?

*Since the GlusterFS documentation has a new face-lift, MediaWiki will no
longer be editable but will only be READ ONLY view mode. Hence, all the
work-in-progress design notes which were maintained on MediaWiki will be
ported to the GitHub repository and placed in "Feature Plans" folder. So,
when you want to upload your work in progess documents you must do a pull
request after the changes are made. This outlines the change in workflow as
compared to MediaWiki.*

A proposal:

Another way to maintain work-in-progress documents in Google docs (or any
other colloborative editing tool) and link them as an index entry in
Feature Plans page on GitHub. This can be an excellent way to track a
document through multiple rounds of collaborative editing in real time.



Stay tuned for a more detailed information about the new contribution
workflow, which will be posted on the new documentation website (i.e.
gluster.readthedocs.org)

We love to hear your feedback on this. Any suggestions/comments regarding
this would help !

--Humble
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.gluster.org/pipermail/gluster-devel/attachments/20150527/8d57cba6/attachment.html>