[Gluster-devel] Inspiration for improving our contributor documentation

[Kaushal M]

On Fri, Jul 18, 2014 at 11:39 AM, Pranith Kumar Karampuri
<pkarampu at redhat.com> wrote:
>
> On 07/18/2014 11:22 AM, Kaushal M wrote:
>>
>> 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.
>
> Still confused :-(. What exactly do you have in mind about things that need
> to be added to the Developer_hub on the wiki? So lets say we complete
> writing all this documentation in .md. Can we point to already added
> documentation on the github repo or do we have to write them again on the
> wiki? By the way this doubt is only about developer documentation. I
> completely agree about the rest of the pages you gave below.

I was mainly talking about the documents under 'Code, development and
style' section in the wikimedia developer hub and our current
documentation in those areas.
For the other developer documents (arch, api, etc.) we can continue
with the current 'markdown in git repo' method. We could add links
from the wiki to these. Also there are tools which can serve markdown
files and we could probably setup such a server as well.

If you are concerned about writing the documentation in 2 different
formats (wiki and markdown), we could consolidate to just 1. There are
extensions to mediawiki, which allows writing entries in markdown.

>
> Pranith
>
>> 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
>>>
>>>
>