[Gluster-devel] [Cross-posted] Re: Gentle Reminder.. (Was: GlusterFS Documentation Improvements - An Update)

[Raghavendra Talur]

*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
    sending patch)


*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
> friendly).
>
> 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 [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
>
>
>
>
>



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.gluster.org/pipermail/gluster-devel/attachments/20150708/a8ba1ba8/attachment-0001.html>