Gluster users - Apr 2015 - [Gluster-devel] Revamping the GlusterFS Documentation...

Hi All, 

"The Gluster Filesystem documentation is not user friendly and
fragmented" and this has been the feedback we have been receiving.

We got back to our drawing board and blueprints and realized that the content
was scattered at various places. These include:

[Static HTML] http://www.gluster.org/documentation/ 
[Mediawiki] http://www.gluster.org/community/documentation/ 
[In-source] https://github.com/gluster/glusterfs/tree/master/doc 
[Markdown] https://github.com/GlusterFS/Notes 

and so on? 

Hence, we started by curating content from various sources including gluster.org
static HTML documentation, glusterfs github repository,
various blog posts and the Community wiki. We also felt the need to improve the
community member's experience with Gluster documentation. This led us to put
some thought into the user interface. As a result we came up with a page which
links all content into a single landing page:

http://www.gluster.org/community/documentation/index.php/Staged_Docs 

This is just our first step to improve our community docs and enhance the
community contribution towards documentation. I would like to thank Humble
Chirammal and Anjana Sriram for the suggestions and directions during the entire
process. I am sure there is lot of scope for improvement.
Hence, request you all to review the content and provide your suggestions. 

Regards, 
Shravan Chandra 

-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://www.gluster.org/pipermail/gluster-users/attachments/20150323/25393e4c/attachment.html>

On 23 Mar 2015, at 07:01, Shravan Chandrashekar <schandra at redhat.com>
wrote:
> Hi All, 
> 
> "The Gluster Filesystem documentation is not user friendly and
fragmented" and this has been the feedback we have been receiving.
> 
> We got back to our drawing board and blueprints and realized that the
content was scattered at various places. These include:
> 
> [Static HTML] http://www.gluster.org/documentation/ 
> [Mediawiki] http://www.gluster.org/community/documentation/ 
> [In-source] https://github.com/gluster/glusterfs/tree/master/doc 
> [Markdown] https://github.com/GlusterFS/Notes 
> 
> and so on? 
> 
> Hence, we started by curating content from various sources including
gluster.org static HTML documentation, glusterfs github repository,
> various blog posts and the Community wiki. We also felt the need to improve
the community member's experience with Gluster documentation. This led us to
put some thought into the user interface. As a result we came up with a page
which links all content into a single landing page:
> 
> http://www.gluster.org/community/documentation/index.php/Staged_Docs 
>  
> This is just our first step to improve our community docs and enhance the
community contribution towards documentation. I would like to thank Humble
Chirammal and Anjana Sriram for the suggestions and directions during the entire
process. I am sure there is lot of scope for improvement.
> Hence, request you all to review the content and provide your suggestions. 
Looks like a good effort.  Is the general concept for this to
become the front/landing page for the main wiki?

Also some initial thoughts:

 * Gluster Ant Logo image - The first letter REALLY looks like a C
   (to me), not a G.  Reads as "Cluster" for me...

   That aside, it looks really good. :)


 * "Getting Started" section ... move it up maybe, before the
   Terminology / Architecture / Additional Resources bit

   This is to make it more obvious for new people.


 * "Terminologies" should probably be "Terminology", as
   "Terminology" is kind of both singular and plural.


 * "All that Developers need to know" ? "Everything Developers
   need to know"

They're my first thoughts anyway. :)

+ Justin

--
GlusterFS - http://www.gluster.org

An open source, distributed file system scaling to several
petabytes, and handling thousands of clients.

My personal twitter: twitter.com/realjustinclift

Looks like it was dropped from gluster-users list. Forwarding exclusively.

----- Forwarded Message -----
From: "Shravan Chandrashekar" <schandra at redhat.com>
To: gluster-users at gluster.org, gluster-devel at gluster.org
Cc: "Satish Mohan" <smohan at redhat.com>, spot at redhat.com,
"Anjana Suparna Sriram" <asriram at redhat.com>
Sent: Monday, March 23, 2015 12:31:15 PM
Subject: Revamping the GlusterFS Documentation...

Hi All, 

"The Gluster Filesystem documentation is not user friendly and
fragmented" and this has been the feedback we have been receiving.

We got back to our drawing board and blueprints and realized that the content
was scattered at various places. These include:

[Static HTML] http://www.gluster.org/documentation/ 
[Mediawiki] http://www.gluster.org/community/documentation/ 
[In-source] https://github.com/gluster/glusterfs/tree/master/doc 
[Markdown] https://github.com/GlusterFS/Notes 

and so on? 

Hence, we started by curating content from various sources including gluster.org
static HTML documentation, glusterfs github repository,
various blog posts and the Community wiki. We also felt the need to improve the
community member's experience with Gluster documentation. This led us to put
some thought into the user interface. As a result we came up with a page which
links all content into a single landing page:

http://www.gluster.org/community/documentation/index.php/Staged_Docs 

This is just our first step to improve our community docs and enhance the
community contribution towards documentation. I would like to thank Humble
Chirammal and Anjana Sriram for the suggestions and directions during the entire
process. I am sure there is lot of scope for improvement.
Hence, request you all to review the content and provide your suggestions. 

Regards, 
Shravan Chandra

Hi Shravan,

Having recently set up geo-replication of Gluster v3.5.3 I can tell you 
that there is effectively almost no documentation. The documentation 
that does exists is primarily focused on describing the differences 
between the current and previous versions. That's completely useless to 
someone wanting to set it up for the first time and not a whole lot 
better for someone who has upgraded. The first, and perhaps most 
crucial, piece of information that's missing is installation 
requirements. Nowhere have I been able to find out exactly which 
components are required on either the master or the slave. In my case 
this was determined by pure trial and error. i.e. Install what I think 
should be needed and then continue installing components until it starts 
to work. Even once that part is done, there is a LOT of documentation 
missing. I recall that when I first set up geo-replication (v3.2 or 
v3.3?) I was able to follow clear and simple step by step instructions 
that almost guaranteed success.

regards,
John


On 23/03/15 18:01, Shravan Chandrashekar wrote:
> *Hi All, *
>
> *"The Gluster Filesystem documentation is not user friendly and 
> fragmented" and this has been the feedback we have been receiving. *
>
> *We got back to our drawing board and blueprints and realized that the 
> content was scattered at various places. These include: *
>
> *[Static HTML] http://www.gluster.org/documentation/ *
> *[Mediawiki] http://www.gluster.org/community/documentation/ *
> *[In-source] https://github.com/gluster/glusterfs/tree/master/doc *
> *[Markdown] https://github.com/GlusterFS/Notes *
>
> *and so on? *
>
> *Hence, we started by curating content from various sources including 
> gluster.org static HTML documentation, glusterfs github repository, *
> *various blog posts and the Community wiki. We also felt the need to 
> improve the community member's experience with Gluster documentation. 
> This led us to put some thought into the user interface. As a result 
> we came up with a page which links all content into a single landing 
> page: *
>
> *http://www.gluster.org/community/documentation/index.php/Staged_Docs *
>
> *This is just our first step to improve our community docs and enhance 
> the community contribution towards documentation. I would like to 
> thank Humble Chirammal and Anjana Sriram for the suggestions and 
> directions during the entire process. I am sure there is lot of scope 
> for improvement. *
> *Hence, request you all to review the content and provide your 
> suggestions. *
>
> Regards,
> Shravan Chandra
>
>
> ______________________________________________________________________
> This email has been scanned by the Symantec Email Security.cloud service.
> For more information please visit http://www.symanteccloud.com
> ______________________________________________________________________
>
>
> _______________________________________________
> Gluster-users mailing list
> Gluster-users at gluster.org
> http://www.gluster.org/mailman/listinfo/gluster-users
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://www.gluster.org/pipermail/gluster-users/attachments/20150325/6eef37f4/attachment.html>

On Mon, Mar 23, 2015 at 12:31 PM, Shravan Chandrashekar
<schandra at redhat.com> wrote:
> Hence, we started by curating content from various sources including
> gluster.org static HTML documentation, glusterfs github repository,
> various blog posts and the Community wiki. We also felt the need to improve
> the community member's experience with Gluster documentation. This led
us to
> put some thought into the user interface. As a result we came up with a
page
> which links all content into a single landing page:
>
> http://www.gluster.org/community/documentation/index.php/Staged_Docs
>
> This is just our first step to improve our community docs and enhance the
> community contribution towards documentation.
This is a strong first step. Thank you for pulling this together. The
feedback at
<https://www.gluster.org/pipermail/gluster-users/2015-March/021275.html>
would indicate that there is a need to put together a blueprint for a
workflow that makes it more easy to contribute, administer and
maintain in a state of publication-readiness.


-- 
sankarshan mukhopadhyay
<https://about.me/sankarshan.mukhopadhyay>