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

[Raghavendra Talur]

On 07/08/2015 07:07 PM, Raghavendra Talur wrote:
>
>
>
>
>
>
>
>
> *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?
>

*My suggestions:*

  * Differentiate between user doc(installation, administration, feature
    summary, tools, FAQ/troubleshooting etc) and developer doc(Design
    doc, developer workflow, coding guidelines etc).
  * User documentation goes to glusterdocs repo and developer
    documentation stays in gluster repo.
  * An user/admin who installed through packages can do a man(and find
    man pages) or google(and find readthedocs pages) without going
    through gerrit/wiki etc.
  * A developer who has cloned gluster repo finds all the development
    related info in the repo itself(git grep etc) and does not need to
    go out of the code base.
  * A patch which changes a struct member should change the relevant
    developer documentation in the same patch set.
  * A patch which changes a user facing behavior should be ideally
    followed by a PR on glusterdocs repo. (patch owner and feature
    maintainer to ensure that).
  * Use github's PR for glusterfsdocs and hence use the comments system
    on github for that.
  * A developer doc change or a new feature proposal should be as patch
    on gluster repo and we can use gerrit's inline comments for
    discussion on that.


>
>
>
>
>
>
>
>
>
>
>
>
>
> 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/70b45365/attachment.html>