<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
Hello All, <br>
<br>
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: <br>
<br>
We plan to use three independent repos for our projects: <br>
<br>
<b>glusterdoc</b>: (<a class="moz-txt-link-freetext"
href="https://github.com/gluster/glusterdocs">https://github.com/gluster/glusterdocs</a>)
:This repo contains and will continue to contain <b>user
documentation</b> such as<i> Install Guide, Admin Guide, Quick
Start Guide.</i> 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:<a class="moz-txt-link-freetext"
href="http://gluster.readthedocs.org/en/latest/">http://gluster.readthedocs.org/en/latest/</a>
. We have a very simplified workflow in place for contribution where
the contributor must have a github account. To edit on <br>
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. <br>
<b><br>
</b><b>glusterfs/doc</b>: This repo will contain <b>developer
related documentation</b> and will reside in the glusterfs source
code repo. A developer who has cloned <i>glusterfs</i> 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 <i>glusterdoc ( <a
class="moz-txt-link-freetext"
href="https://github.com/gluster/glusterdocs">https://github.com/gluster/glusterdocs</a>) </i>
repo .The link to the user facing documentation is a mandatory
requirement for the feature patch to be merged in the <i>glusterfs</i>
repo. <br>
<br>
<b>glusterfs-specs</b>: This repo will contain all files related to
<b><i>feature/release planning</i></b>. Two sub folders will be
created: <i>'</i><i>in progress' and 'Done'</i>. 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: <a
class="moz-txt-link-freetext"
href="https://github.com/openstack/swift-specs">https://github.com/openstack/swift-specs</a>
<br>
<br>
<i>Static Documentation</i>: 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. <br>
<br>
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.<br>
<br>
Regards, <br>
Humble, Shravan, and Anjana<br>
<br>
<div class="moz-cite-prefix">On 06/22/2015 05:24 PM, Shravan
Chandrashekar wrote:<br>
</div>
<blockquote
cite="mid:1173197801.18987629.1434974084592.JavaMail.zimbra@redhat.com"
type="cite">
<pre wrap="">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] <a class="moz-txt-link-freetext" href="https://github.com/gluster/glusterdocs">https://github.com/gluster/glusterdocs</a>
[2] <a class="moz-txt-link-freetext" href="https://github.com/gluster/glusterdocs/issues">https://github.com/gluster/glusterdocs/issues</a>
Regards,
Shravan
----- Original Message -----
From: "Humble Devassy Chirammal" <a class="moz-txt-link-rfc2396E" href="mailto:humble.devassy@gmail.com"><humble.devassy@gmail.com></a>
To: <a class="moz-txt-link-rfc2396E" href="mailto:Gluster-users@gluster.orgList">"Gluster-users@gluster.org List"</a> <a class="moz-txt-link-rfc2396E" href="mailto:gluster-users@gluster.org"><gluster-users@gluster.org></a>, "Gluster Devel" <a class="moz-txt-link-rfc2396E" href="mailto:gluster-devel@gluster.org"><gluster-devel@gluster.org></a>
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 ( <a class="moz-txt-link-freetext" href="https://github.com/gluster/glusterdocs">https://github.com/gluster/glusterdocs</a>) 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
<a class="moz-txt-link-abbreviated" href="mailto:Gluster-devel@gluster.org">Gluster-devel@gluster.org</a>
<a class="moz-txt-link-freetext" href="http://www.gluster.org/mailman/listinfo/gluster-devel">http://www.gluster.org/mailman/listinfo/gluster-devel</a>
</pre>
</blockquote>
<br>
</body>
</html>