Re: [Gluster-devel] Inspiration for improving our contributor documentation
On Fri, Jul 18, 2014 at 11:39 AM, Pranith Kumar Karampuri pkara...@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 pkara...@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@gluster.org http://supercolony.gluster.org/mailman/listinfo/gluster-devel ___ Gluster-devel mailing list Gluster-devel@gluster.org http://supercolony.gluster.org/mailman/listinfo/gluster-devel
Re: [Gluster-devel] Inspiration for improving our contributor documentation
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. 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@gluster.org http://supercolony.gluster.org/mailman/listinfo/gluster-devel ___ Gluster-devel mailing list Gluster-devel@gluster.org http://supercolony.gluster.org/mailman/listinfo/gluster-devel
Re: [Gluster-devel] Inspiration for improving our contributor documentation
On Fri, Jul 18, 2014 at 11:11 AM, Pranith Kumar Karampuri pkara...@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@gluster.org http://supercolony.gluster.org/mailman/listinfo/gluster-devel ___ Gluster-devel mailing list Gluster-devel@gluster.org http://supercolony.gluster.org/mailman/listinfo/gluster-devel
