[Gluster-devel] GlusterFS Documentation Improvements - An Update

[Sankarshan Mukhopadhyay]

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>