Gluster users - May 2015 - GlusterFS Documentation Improvements - An Update

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-users/attachments/20150527/8d57cba6/attachment.html>

On Wed, May 27, 2015 at 7:48 PM, Humble Devassy Chirammal
<humble.devassy at gmail.com> wrote:
> 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.
Thanks for writing this up. Can this workflow/sequence be also visited
from the repo of the docs? It would perhaps be required to put this as
"How to contribute?"
> - 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!
+ FAQs and Common Issues/Known Issues etc
> 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.
It would be of benefit and advantage to have the read-only mode turned
on. This would help avoid 'split-brains' and also create a single
incoming path for content that needs to be maintained as part of the
Documentation community.
> 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.
This is a sound idea as well :)


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

Hello all,

We would like to finalize on the documentation contribution workflow by 26th
June 2015.
As we have not yet received any comments/suggestion, we will confirm the
recommend workflow after 26th June.


Kindly provide your suggestion on how we can improve this workflow. 

Currently, mediawiki is read-only. We have ported most of the documents from
mediawiki to the new repository [1].
If you find any document which is not ported, feel free to raise this by opening
an issue in [2] or if you would
like to port your documents, send a pull request.



[1] https://github.com/gluster/glusterdocs
[2] https://github.com/gluster/glusterdocs/issues

Regards,
Shravan

----- Original Message -----
From: "Humble Devassy Chirammal" <humble.devassy at gmail.com>
To: "Gluster-users at gluster.org List" <gluster-users at
gluster.org>, "Gluster Devel" <gluster-devel at gluster.org>
Sent: Wednesday, May 27, 2015 7:48:16 PM
Subject: [Gluster-devel] GlusterFS Documentation Improvements - An Update


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 (o r 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 


_______________________________________________
Gluster-devel mailing list
Gluster-devel at gluster.org
http://www.gluster.org/mailman/listinfo/gluster-devel

Hello All,

Thank you for the feedback and suggestions provided on the GlusterFS 
Documentation improvements. We have analyzed them and here's a proposal 
to address them:

We plan to use three independent repos for our projects:

*glusterdoc*: (https://github.com/gluster/glusterdocs) :This repo 
contains and will continue to contain *user documentation* such 
as/Install Guide, Admin Guide, Quick Start Guide./ These docs are hosted 
on Read The Docs (RTD). The the documentation source files are in 
Markdown and using MKDocs they are rendered on RTD, for 
ex:http://gluster.readthedocs.org/en/latest/ . We have a very simplified 
workflow in place for contribution where the contributor must have a 
github account. To edit on
github, fork the repository (see top-right of the screen, under your 
user-name). 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.
*
**glusterfs/doc*: This repo will contain *developer related 
documentation* and will reside in the glusterfs source code repo. A 
developer who has cloned /glusterfs/ repo will find all the development 
related info in the repo itself. When a developer is submitting a patch 
for a new feature or a fix which changes the user facing behavior, he 
must simultaneously submit a documentation patch to the /glusterdoc ( 
https://github.com/gluster/glusterdocs) / repo .The link to the user 
facing documentation is a mandatory requirement for the feature patch to 
be merged in the /glusterfs/ repo.

*glusterfs-specs*: This repo will contain all files related to 
*/feature/release planning/*. Two sub folders will be created: /'//in 
progress' and 'Done'/. In the planning phase, the files will reside
in
"in Progress" folder. The developer must move the file to
"done" folder
once the implementation of the feature is completed. Developers will use 
Gerrit to checkout a document, update it and push the new version for 
review. Feature and release planning is very much only done by 
developers and component maintainers. The contents of Done folder are 
kept for historical reasons. They are archived and no one is expected to 
edit or change them even if the corresponding implementation changes at 
some point later in future. The specs repo is modeled after: 
https://github.com/openstack/swift-specs

/Static Documentation/: Currently, Mediawiki is read-only. We have 
ported most of the documents from Mediawiki. There few pages which do 
not qualify to be placed in the above three repos for example, 
Presentations  which will be considered to be placed on the website.

Your thoughts and feedback are the major influences to our constant 
endeavor to make the community documentation better, effective, and 
useful. Please revert with your thoughts and feedback on the above 
proposal outlined by 29th July 2015.

Regards,
Humble, Shravan, and Anjana

On 06/22/2015 05:24 PM, Shravan Chandrashekar wrote:
> Hello all,
>
> We would like to finalize on the documentation contribution workflow by
26th June 2015.
> As we have not yet received any comments/suggestion, we will confirm the
recommend workflow after 26th June.
>
>
> Kindly provide your suggestion on how we can improve this workflow.
>
> Currently, mediawiki is read-only. We have ported most of the documents
from mediawiki to the new repository [1].
> If you find any document which is not ported, feel free to raise this by
opening an issue in [2] or if you would
> like to port your documents, send a pull request.
>
>
>
> [1] https://github.com/gluster/glusterdocs
> [2] https://github.com/gluster/glusterdocs/issues
>
> Regards,
> Shravan
>
> ----- Original Message -----
> From: "Humble Devassy Chirammal" <humble.devassy at
gmail.com>
> To: "Gluster-users at gluster.org List" <gluster-users at
gluster.org>, "Gluster Devel" <gluster-devel at gluster.org>
> Sent: Wednesday, May 27, 2015 7:48:16 PM
> Subject: [Gluster-devel] GlusterFS Documentation Improvements - An Update
>
>
> 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 (o r 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
>
>
> _______________________________________________
> Gluster-devel mailing list
> Gluster-devel at gluster.org
> http://www.gluster.org/mailman/listinfo/gluster-devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://www.gluster.org/pipermail/gluster-users/attachments/20150722/b7a03fd8/attachment.html>