[Gluster-users] Gentle Reminder.. (Was: [Gluster-devel] GlusterFS Documentation Improvements - An Update)
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" To: "Gluster-users@gluster.org List" , "Gluster Devel" 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-de...@gluster.org http://www.gluster.org/mailman/listinfo/gluster-devel ___ Gluster-users mailing list Gluster-users@gluster.
[Gluster-users] Revamping the GlusterFS Documentation...
Hi John, Thank you, thats a really valuable feedback. We are working on updating the documentation and will ensure to address this gap. Thanks and regards, Shravan Forwarded Message Subject:Re: [Gluster-users] Revamping the GlusterFS Documentation... Date: Wed, 25 Mar 2015 08:59:10 +1100 From: John Gardeniers To: gluster-users@gluster.org 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@gluster.org > http://www.gluster.org/mailman/listinfo/gluster-users ___ Gluster-users mailing list Gluster-users@gluster.org http://www.gluster.org/mailman/listinfo/gluster-users ___ Gluster-users mailing list Gluster-users@gluster.org http://www.gluster.org/mailman/listinfo/gluster-users
Re: [Gluster-users] [Gluster-devel] Revamping the GlusterFS Documentation...
Yes, We are thinking about a front/landing page for the documentation with better UI/UX. The minor changes that you had suggested, have been made :) -Shravan - Original Message - From: "Justin Clift" To: "Shravan Chandrashekar" Cc: gluster-users@gluster.org, gluster-de...@gluster.org, "Anjana Suparna Sriram" , s...@redhat.com Sent: Tuesday, March 24, 2015 3:04:39 AM Subject: Re: [Gluster-devel] Revamping the GlusterFS Documentation... On 23 Mar 2015, at 07: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. 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 ___ Gluster-users mailing list Gluster-users@gluster.org http://www.gluster.org/mailman/listinfo/gluster-users
[Gluster-users] Fwd: Revamping the GlusterFS Documentation...
Looks like it was dropped from gluster-users list. Forwarding exclusively. - Forwarded Message - From: "Shravan Chandrashekar" To: gluster-users@gluster.org, gluster-de...@gluster.org Cc: "Satish Mohan" , s...@redhat.com, "Anjana Suparna Sriram" 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 ___ Gluster-users mailing list Gluster-users@gluster.org http://www.gluster.org/mailman/listinfo/gluster-users
[Gluster-users] 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 ___ Gluster-users mailing list Gluster-users@gluster.org http://www.gluster.org/mailman/listinfo/gluster-users
