[Gluster-devel] [Cross-posted] Re: Gentle Reminder.. (Was: GlusterFS Documentation Improvements - An Update)
rtalur at redhat.com
Wed Jul 8 13:37:55 UTC 2015
*Top posting with summary of mails above to enable better discussion*
*Premise of original mail:*
* Gluster related documentation was spread across
wiki/website-html/gluster-repo and difficult to find.
* We want a new place for documentation(preferebly one single place)
* The workflow to contribute should be easy for non-developers
too.(should definitely not involve cloning repo from gerrit and
*Unanswered questions/ Concerns raised*
* Developer documentation like struct members and their uses should be
in repo so that developers update it along with code changes, else
there is a good chance docs go outdated.
* What is the reviewing mechanism for patches against documentation?
* What tool/system gives a good inline commenting feature and can be
used for discussion?
On 06/23/2015 04:36 PM, Sankarshan Mukhopadhyay wrote:
> On Mon, Jun 22, 2015 at 5:24 PM, Shravan Chandrashekar
> <schandra at redhat.com> wrote:
>> 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.
> There are a couple of aspects which need to be quickly looked through.
> (a) a write-up of somewhat detail providing an overview of the new
> workflow; how contributors can participate; reviewing mechanism for
> patches against documentation; merge and release paths/cadence
> (b) at <http://review.gluster.org/#/c/11129/> Niels has a comment
> about "about design of structures used in the code" and how he thinks
> that it is appropriate if "it stays part of the sources and does not
> move out."
> He also says "For example, I would like to document some of the memory
> layout structures and functions, but this documentation will include
> source-code comments and a .txt or .md file with additional details.
> Spitting that makes it more difficult to keep in sync."
> In this particular example, I'd probably say that it would be better
> that such documentation is also part of the docs repo. It lends itself
> to re-use as and when required (this particular example seems re-use
> I'd request that this switch-over to the new workflow and repositories
> go ahead with the absolute "documentation" content. Examples/cases
> like the above mentioned by Niels can be resolved via discussion and
> probably not block the switch.
>> Currently, mediawiki is read-only. We have ported most of the documents from mediawiki to the new repository .
>> If you find any document which is not ported, feel free to raise this by opening an issue in  or if you would
>> like to port your documents, send a pull request.
>>  https://github.com/gluster/glusterdocs
>>  https://github.com/gluster/glusterdocs/issues
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Gluster-devel