[Gluster-devel] Inspiration for improving our contributor documentation

[Kaushal M]

On Fri, Jul 18, 2014 at 11:11 AM, Pranith Kumar Karampuri
<pkarampu at redhat.com> wrote:
>
> On 07/17/2014 07:25 PM, Kaushal M wrote:
>>
>> I came across mediawiki's developer documentation and guides when
>> browsing. These docs felt really good to me, and easy to approach.
>> I feel that we should take inspiration from them and start enhancing
>> our docs. (Outright copying with modifications as necessary, could
>> work too. But that just doesn't feel right)
>>
>> Any volunteers?
>> (I'll start as soon as I finish with the developer documentation for
>> data structures for the components I volunteered earlier)
>>
>> ~kaushal
>>
>> [0] - https://www.mediawiki.org/wiki/Developer_hub
>
> I love the idea but not sure about the implementation. i.e. considering we
> already started with .md pages, why not have same kind of pages as .md files
> in /doc of gluster? We can modify the README in our project so that people
> can browse all the details in github? Please let me know your thoughts.

These kinds of docs need to indexable and searchable by search
engines. Only then will they be useful. I don't think markdown files
in the source would be good place for these.
The other docs related to source/code documentation can be provided in
the source as we are attempting to provide now. These need to be
directly accessible for devs when developing, so having them in the
git repo is good.

> Pranith
>>
>> [1] - https://www.mediawiki.org/wiki/Category:New_contributors
>> [2] - https://www.mediawiki.org/wiki/Gerrit/Code_review
>> [3] - https://www.mediawiki.org/wiki/Gerrit
>> [4] - https://www.mediawiki.org/wiki/Gerrit/Tutorial
>> [5] - https://www.mediawiki.org/wiki/Gerrit/Getting_started
>> [6] - https://www.mediawiki.org/wiki/Gerrit/Advanced_usage
>> ... and lots more.
>> _______________________________________________
>> Gluster-devel mailing list
>> Gluster-devel at gluster.org
>> http://supercolony.gluster.org/mailman/listinfo/gluster-devel
>
>