Re: [Input request] Rethinking Plugin docs
I'm more supportive of Michal's thoughts, although I understand the practicality of Andrew's approach. Ideal world: - plugins.cordova.io renders all markdown files in docs/**/*.md - plugins.cordova.io allows switching the language (globally across the site, like any normal website) Algorithm for default npm page: 1. If exists docs/index.md 2. If exists docs/en/index.md 3. If exists README.md README.md vs index.md - README.md (or just README) is a top-level file for projects - Our documentation is a mark-up language that's render to HTML files - Our documentation should use the naming pattern of HTML files NOT project distribution files - README.md should not appear in our docs directory Reality - Anis will know best, but this approach might not be do-able in the short-term. - Ideally, our next doc generator could be pluggable into plugins.cordova.io to do the heavy lifting - The multiple pages could be displayed as separate HTML pages or simply the GitHub gist-style for multiple files. - A short-term solution may be: 1. If only one markdown file exists in docs/**/*.md, then render it as the npm page 2. If multiple markdown files exist in docs/**/*.md, then render a table of contents as the npm page (from all the files) On Wed, Mar 5, 2014 at 12:23 PM, Michal Mocny mmo...@chromium.org wrote: on plugman publish: if (exists docs/en/README.md) use that; else use README.md; ?? The reason I suggest that is because I think relative links will not work very well if we have the EN docs at a different level than the other languages. -Michal On Wed, Mar 5, 2014 at 2:50 PM, Andrew Grieve agri...@chromium.org wrote: That's a hairy point of this change for sure. Not sure what the best would be. Maybe treat doc/fr/README.md as based on /README.md I think the majority of third-party plugins will write only README.md, and have no doc/ at all, so having it be a special case is worth it I think. On Wed, Mar 5, 2014 at 2:44 PM, Michal Mocny mmo...@chromium.org wrote: How does that work with proposal for i18n? Ideally the docs/ tree is identical in each language, so I think we want the top level docs (README.md or index.md) to be in the docs/en/ tree as well. Perhaps we leave the README.md empty and change plugman publish to bundle docs/en/index.md instead? Or perhaps we make README.md == docs/en/index.md always? -Michal On Wed, Mar 5, 2014 at 2:25 PM, Andrew Grieve agri...@chromium.org wrote: The discussion so far has been: - npm, github, surface README.md prominently - our README.md files are essentially empty - let's delete doc/index.md and put it all in README.md - plugins.cordova.io will render the README.md prominently On Wed, Mar 5, 2014 at 1:25 PM, Michael Brooks mich...@michaelbrooks.ca wrote: Andrew, do you mean merging all of the documentation into the README.md or do you mean translating the README.md to other languages? On Tue, Mar 4, 2014 at 10:05 AM, Andrew Grieve agri...@chromium.org wrote: Michael - any input here on merging doc - README.md?, or if we do this how translations should go? e.g. README.md, doc/fr/README.md On Mon, Feb 24, 2014 at 3:27 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: README.md merge +1 I understand the idea behind keeping the documentation outside of the README.md but given that the how to contribute and other info is generally the same across all of the plugins and is available on the wiki, etc. it's probably redundant to put it in each repo as well. That being said it probably wouldn't hurt to have a link on the top of the README.md's pointing back to the main cordova project info. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat | [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Steven Gill stevengil...@gmail.com To:dev@cordova.apache.org dev@cordova.apache.org Cc:Lisa Seacat DeLuca/San Francisco/IBM@IBMUS, Michael Brooks mich...@michaelbrooks.ca Date:02/24/2014 03:08 PM Subject:Re: [Input request] Rethinking Plugin docs -- I personally think we should merge the two into README.md. Our readme files in the plugins are useless right now. Might as well combine some
Re: [Input request] Rethinking Plugin docs
Andrew, do you mean merging all of the documentation into the README.md or do you mean translating the README.md to other languages? On Tue, Mar 4, 2014 at 10:05 AM, Andrew Grieve agri...@chromium.org wrote: Michael - any input here on merging doc - README.md?, or if we do this how translations should go? e.g. README.md, doc/fr/README.md On Mon, Feb 24, 2014 at 3:27 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: README.md merge +1 I understand the idea behind keeping the documentation outside of the README.md but given that the how to contribute and other info is generally the same across all of the plugins and is available on the wiki, etc. it's probably redundant to put it in each repo as well. That being said it probably wouldn't hurt to have a link on the top of the README.md's pointing back to the main cordova project info. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Steven Gill stevengil...@gmail.com To:dev@cordova.apache.org dev@cordova.apache.org Cc:Lisa Seacat DeLuca/San Francisco/IBM@IBMUS, Michael Brooks mich...@michaelbrooks.ca Date:02/24/2014 03:08 PM Subject:Re: [Input request] Rethinking Plugin docs -- I personally think we should merge the two into README.md. Our readme files in the plugins are useless right now. Might as well combine some of the info that should be in the readme + index.md so we have all of the important information shown prominently. On Mon, Feb 24, 2014 at 11:53 AM, Andrew Grieve agri...@chromium.org wrote: +Michael Might be helpful to write out expanded README.md files for our plugins. Right now, they just contain a title and a link to the docs: https://github.com/apache/cordova-plugin-file What it is is covered by the first paragraph of the docs already I think. How to contribute is pretty obvious for most github-hosted projects, but I don't think that would hurt as part of the documentation either. On Mon, Feb 24, 2014 at 2:37 PM, Brian LeRoux b...@brian.io wrote: I think Mike's main consideration is that the README.md is a place for general project info (what it is, how to contribute, etc) whereas documentation, inc translations, should be in a dedicated space as standard convention so we can tool it. (Something like this: `doc/[lang]/ index.md `.) On Mon, Feb 24, 2014 at 11:26 AM, Andrew Grieve agri...@google.com wrote: That was basically the question in my head as I was typing... I'd be happy with having just a README.md, and allowing it to link to relative .md paths if it wanted to. On Mon, Feb 24, 2014 at 2:21 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: If README.md is the standard why not just call all of them README and not have an index.md file at all for the plugins. What is the advantage of having both? Seems more confusing than anything. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat | [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Andrew Grieve agri...@chromium.org To:dev dev@cordova.apache.org Date:02/24/2014 01:41 PM Subject:Re: [Input request] Rethinking Plugin docs Sent by:agri...@google.com -- On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard cmarc...@gmail.com wrote: On Feb 24, 2014, at 12:32 PM, Andrew Grieve agri...@chromium.org wrote: - We may also want to include README.md files in the translations. doc/fr/index.md doc/fr/README.md What content do you forsee being in README.md other than a table-of-contents to the languages? Or in other words, would it be public-facing content that could be collapsed in to the rest of the plugin docs? On npmjs.org and on github, README.md's are the files that are shown most prominently. So, I speculate that many plugins will not provide a doc/ index.md, and instead provide only a README.md. - We don't need the version in the directory since we can use git tags to find
Re: [Input request] Rethinking Plugin docs
The discussion so far has been: - npm, github, surface README.md prominently - our README.md files are essentially empty - let's delete doc/index.md and put it all in README.md - plugins.cordova.io will render the README.md prominently On Wed, Mar 5, 2014 at 1:25 PM, Michael Brooks mich...@michaelbrooks.cawrote: Andrew, do you mean merging all of the documentation into the README.md or do you mean translating the README.md to other languages? On Tue, Mar 4, 2014 at 10:05 AM, Andrew Grieve agri...@chromium.org wrote: Michael - any input here on merging doc - README.md?, or if we do this how translations should go? e.g. README.md, doc/fr/README.md On Mon, Feb 24, 2014 at 3:27 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: README.md merge +1 I understand the idea behind keeping the documentation outside of the README.md but given that the how to contribute and other info is generally the same across all of the plugins and is available on the wiki, etc. it's probably redundant to put it in each repo as well. That being said it probably wouldn't hurt to have a link on the top of the README.md's pointing back to the main cordova project info. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Steven Gill stevengil...@gmail.com To:dev@cordova.apache.org dev@cordova.apache.org Cc:Lisa Seacat DeLuca/San Francisco/IBM@IBMUS, Michael Brooks mich...@michaelbrooks.ca Date:02/24/2014 03:08 PM Subject:Re: [Input request] Rethinking Plugin docs -- I personally think we should merge the two into README.md. Our readme files in the plugins are useless right now. Might as well combine some of the info that should be in the readme + index.md so we have all of the important information shown prominently. On Mon, Feb 24, 2014 at 11:53 AM, Andrew Grieve agri...@chromium.org wrote: +Michael Might be helpful to write out expanded README.md files for our plugins. Right now, they just contain a title and a link to the docs: https://github.com/apache/cordova-plugin-file What it is is covered by the first paragraph of the docs already I think. How to contribute is pretty obvious for most github-hosted projects, but I don't think that would hurt as part of the documentation either. On Mon, Feb 24, 2014 at 2:37 PM, Brian LeRoux b...@brian.io wrote: I think Mike's main consideration is that the README.md is a place for general project info (what it is, how to contribute, etc) whereas documentation, inc translations, should be in a dedicated space as standard convention so we can tool it. (Something like this: `doc/[lang]/ index.md `.) On Mon, Feb 24, 2014 at 11:26 AM, Andrew Grieve agri...@google.com wrote: That was basically the question in my head as I was typing... I'd be happy with having just a README.md, and allowing it to link to relative .md paths if it wanted to. On Mon, Feb 24, 2014 at 2:21 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: If README.md is the standard why not just call all of them README and not have an index.md file at all for the plugins. What is the advantage of having both? Seems more confusing than anything. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat | [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Andrew Grieve agri...@chromium.org To:dev dev@cordova.apache.org Date:02/24/2014 01:41 PM Subject:Re: [Input request] Rethinking Plugin docs Sent by:agri...@google.com -- On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard cmarc...@gmail.com wrote: On Feb 24, 2014, at 12:32 PM, Andrew Grieve agri...@chromium.org wrote: - We may also want to include README.md files in the translations. doc/fr/index.md doc/fr/README.md What content do you forsee being in README.md other than a table-of-contents
Re: [Input request] Rethinking Plugin docs
How does that work with proposal for i18n? Ideally the docs/ tree is identical in each language, so I think we want the top level docs (README.md or index.md) to be in the docs/en/ tree as well. Perhaps we leave the README.md empty and change plugman publish to bundle docs/en/index.md instead? Or perhaps we make README.md == docs/en/index.md always? -Michal On Wed, Mar 5, 2014 at 2:25 PM, Andrew Grieve agri...@chromium.org wrote: The discussion so far has been: - npm, github, surface README.md prominently - our README.md files are essentially empty - let's delete doc/index.md and put it all in README.md - plugins.cordova.io will render the README.md prominently On Wed, Mar 5, 2014 at 1:25 PM, Michael Brooks mich...@michaelbrooks.ca wrote: Andrew, do you mean merging all of the documentation into the README.md or do you mean translating the README.md to other languages? On Tue, Mar 4, 2014 at 10:05 AM, Andrew Grieve agri...@chromium.org wrote: Michael - any input here on merging doc - README.md?, or if we do this how translations should go? e.g. README.md, doc/fr/README.md On Mon, Feb 24, 2014 at 3:27 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: README.md merge +1 I understand the idea behind keeping the documentation outside of the README.md but given that the how to contribute and other info is generally the same across all of the plugins and is available on the wiki, etc. it's probably redundant to put it in each repo as well. That being said it probably wouldn't hurt to have a link on the top of the README.md's pointing back to the main cordova project info. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Steven Gill stevengil...@gmail.com To:dev@cordova.apache.org dev@cordova.apache.org Cc:Lisa Seacat DeLuca/San Francisco/IBM@IBMUS, Michael Brooks mich...@michaelbrooks.ca Date:02/24/2014 03:08 PM Subject:Re: [Input request] Rethinking Plugin docs -- I personally think we should merge the two into README.md. Our readme files in the plugins are useless right now. Might as well combine some of the info that should be in the readme + index.md so we have all of the important information shown prominently. On Mon, Feb 24, 2014 at 11:53 AM, Andrew Grieve agri...@chromium.org wrote: +Michael Might be helpful to write out expanded README.md files for our plugins. Right now, they just contain a title and a link to the docs: https://github.com/apache/cordova-plugin-file What it is is covered by the first paragraph of the docs already I think. How to contribute is pretty obvious for most github-hosted projects, but I don't think that would hurt as part of the documentation either. On Mon, Feb 24, 2014 at 2:37 PM, Brian LeRoux b...@brian.io wrote: I think Mike's main consideration is that the README.md is a place for general project info (what it is, how to contribute, etc) whereas documentation, inc translations, should be in a dedicated space as standard convention so we can tool it. (Something like this: `doc/[lang]/ index.md `.) On Mon, Feb 24, 2014 at 11:26 AM, Andrew Grieve agri...@google.com wrote: That was basically the question in my head as I was typing... I'd be happy with having just a README.md, and allowing it to link to relative .md paths if it wanted to. On Mon, Feb 24, 2014 at 2:21 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: If README.md is the standard why not just call all of them README and not have an index.md file at all for the plugins. What is the advantage of having both? Seems more confusing than anything. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat | [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Andrew Grieve agri...@chromium.org To:dev dev@cordova.apache.org Date:02/24/2014 01:41 PM
Re: [Input request] Rethinking Plugin docs
That's a hairy point of this change for sure. Not sure what the best would be. Maybe treat doc/fr/README.md as based on /README.md I think the majority of third-party plugins will write only README.md, and have no doc/ at all, so having it be a special case is worth it I think. On Wed, Mar 5, 2014 at 2:44 PM, Michal Mocny mmo...@chromium.org wrote: How does that work with proposal for i18n? Ideally the docs/ tree is identical in each language, so I think we want the top level docs (README.md or index.md) to be in the docs/en/ tree as well. Perhaps we leave the README.md empty and change plugman publish to bundle docs/en/index.md instead? Or perhaps we make README.md == docs/en/index.md always? -Michal On Wed, Mar 5, 2014 at 2:25 PM, Andrew Grieve agri...@chromium.org wrote: The discussion so far has been: - npm, github, surface README.md prominently - our README.md files are essentially empty - let's delete doc/index.md and put it all in README.md - plugins.cordova.io will render the README.md prominently On Wed, Mar 5, 2014 at 1:25 PM, Michael Brooks mich...@michaelbrooks.ca wrote: Andrew, do you mean merging all of the documentation into the README.md or do you mean translating the README.md to other languages? On Tue, Mar 4, 2014 at 10:05 AM, Andrew Grieve agri...@chromium.org wrote: Michael - any input here on merging doc - README.md?, or if we do this how translations should go? e.g. README.md, doc/fr/README.md On Mon, Feb 24, 2014 at 3:27 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: README.md merge +1 I understand the idea behind keeping the documentation outside of the README.md but given that the how to contribute and other info is generally the same across all of the plugins and is available on the wiki, etc. it's probably redundant to put it in each repo as well. That being said it probably wouldn't hurt to have a link on the top of the README.md's pointing back to the main cordova project info. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat | [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Steven Gill stevengil...@gmail.com To:dev@cordova.apache.org dev@cordova.apache.org Cc:Lisa Seacat DeLuca/San Francisco/IBM@IBMUS, Michael Brooks mich...@michaelbrooks.ca Date:02/24/2014 03:08 PM Subject:Re: [Input request] Rethinking Plugin docs -- I personally think we should merge the two into README.md. Our readme files in the plugins are useless right now. Might as well combine some of the info that should be in the readme + index.md so we have all of the important information shown prominently. On Mon, Feb 24, 2014 at 11:53 AM, Andrew Grieve agri...@chromium.org wrote: +Michael Might be helpful to write out expanded README.md files for our plugins. Right now, they just contain a title and a link to the docs: https://github.com/apache/cordova-plugin-file What it is is covered by the first paragraph of the docs already I think. How to contribute is pretty obvious for most github-hosted projects, but I don't think that would hurt as part of the documentation either. On Mon, Feb 24, 2014 at 2:37 PM, Brian LeRoux b...@brian.io wrote: I think Mike's main consideration is that the README.md is a place for general project info (what it is, how to contribute, etc) whereas documentation, inc translations, should be in a dedicated space as standard convention so we can tool it. (Something like this: `doc/[lang]/ index.md `.) On Mon, Feb 24, 2014 at 11:26 AM, Andrew Grieve agri...@google.com wrote: That was basically the question in my head as I was typing... I'd be happy with having just a README.md, and allowing it to link to relative .md paths if it wanted to. On Mon, Feb 24, 2014 at 2:21 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: If README.md is the standard why not just call all of them README and not have an index.md file at all for the plugins. What is the advantage of having both? Seems more confusing than anything. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel
Re: [Input request] Rethinking Plugin docs
on plugman publish: if (exists docs/en/README.md) use that; else use README.md; ?? The reason I suggest that is because I think relative links will not work very well if we have the EN docs at a different level than the other languages. -Michal On Wed, Mar 5, 2014 at 2:50 PM, Andrew Grieve agri...@chromium.org wrote: That's a hairy point of this change for sure. Not sure what the best would be. Maybe treat doc/fr/README.md as based on /README.md I think the majority of third-party plugins will write only README.md, and have no doc/ at all, so having it be a special case is worth it I think. On Wed, Mar 5, 2014 at 2:44 PM, Michal Mocny mmo...@chromium.org wrote: How does that work with proposal for i18n? Ideally the docs/ tree is identical in each language, so I think we want the top level docs (README.md or index.md) to be in the docs/en/ tree as well. Perhaps we leave the README.md empty and change plugman publish to bundle docs/en/index.md instead? Or perhaps we make README.md == docs/en/index.md always? -Michal On Wed, Mar 5, 2014 at 2:25 PM, Andrew Grieve agri...@chromium.org wrote: The discussion so far has been: - npm, github, surface README.md prominently - our README.md files are essentially empty - let's delete doc/index.md and put it all in README.md - plugins.cordova.io will render the README.md prominently On Wed, Mar 5, 2014 at 1:25 PM, Michael Brooks mich...@michaelbrooks.ca wrote: Andrew, do you mean merging all of the documentation into the README.md or do you mean translating the README.md to other languages? On Tue, Mar 4, 2014 at 10:05 AM, Andrew Grieve agri...@chromium.org wrote: Michael - any input here on merging doc - README.md?, or if we do this how translations should go? e.g. README.md, doc/fr/README.md On Mon, Feb 24, 2014 at 3:27 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: README.md merge +1 I understand the idea behind keeping the documentation outside of the README.md but given that the how to contribute and other info is generally the same across all of the plugins and is available on the wiki, etc. it's probably redundant to put it in each repo as well. That being said it probably wouldn't hurt to have a link on the top of the README.md's pointing back to the main cordova project info. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat | [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Steven Gill stevengil...@gmail.com To:dev@cordova.apache.org dev@cordova.apache.org Cc:Lisa Seacat DeLuca/San Francisco/IBM@IBMUS, Michael Brooks mich...@michaelbrooks.ca Date:02/24/2014 03:08 PM Subject:Re: [Input request] Rethinking Plugin docs -- I personally think we should merge the two into README.md. Our readme files in the plugins are useless right now. Might as well combine some of the info that should be in the readme + index.md so we have all of the important information shown prominently. On Mon, Feb 24, 2014 at 11:53 AM, Andrew Grieve agri...@chromium.org wrote: +Michael Might be helpful to write out expanded README.md files for our plugins. Right now, they just contain a title and a link to the docs: https://github.com/apache/cordova-plugin-file What it is is covered by the first paragraph of the docs already I think. How to contribute is pretty obvious for most github-hosted projects, but I don't think that would hurt as part of the documentation either. On Mon, Feb 24, 2014 at 2:37 PM, Brian LeRoux b...@brian.io wrote: I think Mike's main consideration is that the README.md is a place for general project info (what it is, how to contribute, etc) whereas documentation, inc translations, should be in a dedicated space as standard convention so we can tool it. (Something like this: `doc/[lang]/ index.md `.) On Mon, Feb 24, 2014 at 11:26 AM, Andrew Grieve agri...@google.com wrote: That was basically the question in my head as I was typing... I'd be happy with having just a README.md, and allowing it to link to relative .md
Re: [Input request] Rethinking Plugin docs
Michael - any input here on merging doc - README.md?, or if we do this how translations should go? e.g. README.md, doc/fr/README.md On Mon, Feb 24, 2014 at 3:27 PM, Lisa Seacat DeLuca ldel...@us.ibm.comwrote: README.md merge +1 I understand the idea behind keeping the documentation outside of the README.md but given that the how to contribute and other info is generally the same across all of the plugins and is available on the wiki, etc. it's probably redundant to put it in each repo as well. That being said it probably wouldn't hurt to have a link on the top of the README.md's pointing back to the main cordova project info. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org*ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com*http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin]http://www.linkedin.com/in/lisaseacat From:Steven Gill stevengil...@gmail.com To:dev@cordova.apache.org dev@cordova.apache.org Cc:Lisa Seacat DeLuca/San Francisco/IBM@IBMUS, Michael Brooks mich...@michaelbrooks.ca Date:02/24/2014 03:08 PM Subject:Re: [Input request] Rethinking Plugin docs -- I personally think we should merge the two into README.md. Our readme files in the plugins are useless right now. Might as well combine some of the info that should be in the readme + index.md so we have all of the important information shown prominently. On Mon, Feb 24, 2014 at 11:53 AM, Andrew Grieve agri...@chromium.org wrote: +Michael Might be helpful to write out expanded README.md files for our plugins. Right now, they just contain a title and a link to the docs: https://github.com/apache/cordova-plugin-file What it is is covered by the first paragraph of the docs already I think. How to contribute is pretty obvious for most github-hosted projects, but I don't think that would hurt as part of the documentation either. On Mon, Feb 24, 2014 at 2:37 PM, Brian LeRoux b...@brian.io wrote: I think Mike's main consideration is that the README.md is a place for general project info (what it is, how to contribute, etc) whereas documentation, inc translations, should be in a dedicated space as standard convention so we can tool it. (Something like this: `doc/[lang]/ index.md `.) On Mon, Feb 24, 2014 at 11:26 AM, Andrew Grieve agri...@google.com wrote: That was basically the question in my head as I was typing... I'd be happy with having just a README.md, and allowing it to link to relative .md paths if it wanted to. On Mon, Feb 24, 2014 at 2:21 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: If README.md is the standard why not just call all of them README and not have an index.md file at all for the plugins. What is the advantage of having both? Seems more confusing than anything. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Andrew Grieve agri...@chromium.org To:dev dev@cordova.apache.org Date:02/24/2014 01:41 PM Subject:Re: [Input request] Rethinking Plugin docs Sent by:agri...@google.com -- On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard cmarc...@gmail.com wrote: On Feb 24, 2014, at 12:32 PM, Andrew Grieve agri...@chromium.org wrote: - We may also want to include README.md files in the translations. doc/fr/index.md doc/fr/README.md What content do you forsee being in README.md other than a table-of-contents to the languages? Or in other words, would it be public-facing content that could be collapsed in to the rest of the plugin docs? On npmjs.org and on github, README.md's are the files that are shown most prominently. So, I speculate that many plugins will not provide a doc/ index.md, and instead provide only a README.md. - We don't need the version in the directory since we can use git tags to find old versions That makes sense.
Re: [Input request] Rethinking Plugin docs
Translation Update: 1. I have updated the automated scripts for crowdin to pull in the documentation for cordova-docs and the 17 plugin repository .md files. There are currently 72 files available for translation in our tooling. It is available as always, here: https://crowdin.net/project/cordova. For information on the nitty-gritty checkout the wiki page: https://wiki.apache.org/cordova/CordovaTranslations 2. We kinda discussed the way the documentation is currently referencing the english version of the documentation within github. We'll need to come up with a better way of building the plugin documentation into the current html pages. I opened a JIRA issue: https://issues.apache.org/jira/browse/CB-6137 3. Another issue that was brought to my attention by Carlos (thanks Carlos) is there is currently no clear way for users to know that translations exist. So I have opened a JIRA issue: https://issues.apache.org/jira/browse/CB-6136. It would be nice if to the left of the drop down there was a message such as Switch languages or documentation version here: Please share with your social network a tweet to get people to help with translations. ex. The @apachecordova documentation is now broken out for each plugin. We need YOUR help translating! @crowdin https://crowdin.net/project/cordova Thanks, Lisa Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | ldel...@apache.org | | ldel...@us.ibm.com | lisaseacat.com | | From: Shazron shaz...@gmail.com To: dev@cordova.apache.org dev@cordova.apache.org Date: 02/24/2014 12:47 PM Subject:Re: [Input request] Rethinking Plugin docs I agree with Andrew's points in #1. We have to update the 3.4.0 docs nonetheless, since the URLs do not point to a specific tagged version. On Mon, Feb 24, 2014 at 9:32 AM, Andrew Grieve agri...@chromium.org wrote: My thoughts here: 1. - We may also want to include README.md files in the translations. - I like not having a subdir for en/ so as to differentiate it as the one the others are based off of - We don't need the version in the directory since we can use git tags to find old versions maybe: doc/index.md doc/fr/index.md doc/fr/README.md doc/es/index.md doc/es/README.md 2. The plan is to render these on plugins.cordova.io, so we can certainly add logic there to maintain language pref. On Mon, Feb 24, 2014 at 11:13 AM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: I noticed for the 3.4 release that the documentation for each of the plugins redirects to the github repository for each plugin and a document under doc/index.md http://cordova.apache.org/docs/en/3.4.0/cordova_plugins_pluginapis.md.html#Plugin%20APIs If we want to have translations for each of the plugins then we're going to need to rethink this a little. Here are two options: 1. similar to the cordova-docs dir, we could have a language directory as the parent. ex. doc/en/index.md and while we're at it we probably need the version as well ex. doc/en/3.4.0/index.md If we do this then at least we can have the documentation for each language. But that doesn't solve the problem of the user being always redirected to the english version of the documentation and not their specific language. 2. Is it hard to do a build of the index.md for each plugin similar to how we build the cordova-doc md files into html files? If it were seamless and part of the other documentation it would make my life *coughTranslationcough* so much easier. Plus it won't be as confusing on end users having to choose their language more than one time. It'd be nice to get some input from everyone before I start writing a complicated automated script for the plugin translations. Lisa Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat
Re: [Input request] Rethinking Plugin docs
My thoughts here: 1. - We may also want to include README.md files in the translations. - I like not having a subdir for en/ so as to differentiate it as the one the others are based off of - We don't need the version in the directory since we can use git tags to find old versions maybe: doc/index.md doc/fr/index.md doc/fr/README.md doc/es/index.md doc/es/README.md 2. The plan is to render these on plugins.cordova.io, so we can certainly add logic there to maintain language pref. On Mon, Feb 24, 2014 at 11:13 AM, Lisa Seacat DeLuca ldel...@us.ibm.comwrote: I noticed for the 3.4 release that the documentation for each of the plugins redirects to the github repository for each plugin and a document under doc/index.md http://cordova.apache.org/docs/en/3.4.0/cordova_plugins_pluginapis.md.html#Plugin%20APIs If we want to have translations for each of the plugins then we're going to need to rethink this a little. Here are two options: 1. similar to the cordova-docs dir, we could have a language directory as the parent. ex. doc/en/index.md and while we're at it we probably need the version as well ex. doc/en/3.4.0/index.md If we do this then at least we can have the documentation for each language. But that doesn't solve the problem of the user being always redirected to the english version of the documentation and not their specific language. 2. Is it hard to do a build of the index.md for each plugin similar to how we build the cordova-doc md files into html files? If it were seamless and part of the other documentation it would make my life *coughTranslationcough* so much easier. Plus it won't be as confusing on end users having to choose their language more than one time. It'd be nice to get some input from everyone before I start writing a complicated automated script for the plugin translations. Lisa Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org*ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com*http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin]http://www.linkedin.com/in/lisaseacat
Re: [Input request] Rethinking Plugin docs
I agree with Andrew's points in #1. We have to update the 3.4.0 docs nonetheless, since the URLs do not point to a specific tagged version. On Mon, Feb 24, 2014 at 9:32 AM, Andrew Grieve agri...@chromium.org wrote: My thoughts here: 1. - We may also want to include README.md files in the translations. - I like not having a subdir for en/ so as to differentiate it as the one the others are based off of - We don't need the version in the directory since we can use git tags to find old versions maybe: doc/index.md doc/fr/index.md doc/fr/README.md doc/es/index.md doc/es/README.md 2. The plan is to render these on plugins.cordova.io, so we can certainly add logic there to maintain language pref. On Mon, Feb 24, 2014 at 11:13 AM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: I noticed for the 3.4 release that the documentation for each of the plugins redirects to the github repository for each plugin and a document under doc/index.md http://cordova.apache.org/docs/en/3.4.0/cordova_plugins_pluginapis.md.html#Plugin%20APIs If we want to have translations for each of the plugins then we're going to need to rethink this a little. Here are two options: 1. similar to the cordova-docs dir, we could have a language directory as the parent. ex. doc/en/index.md and while we're at it we probably need the version as well ex. doc/en/3.4.0/index.md If we do this then at least we can have the documentation for each language. But that doesn't solve the problem of the user being always redirected to the english version of the documentation and not their specific language. 2. Is it hard to do a build of the index.md for each plugin similar to how we build the cordova-doc md files into html files? If it were seamless and part of the other documentation it would make my life *coughTranslationcough* so much easier. Plus it won't be as confusing on end users having to choose their language more than one time. It'd be nice to get some input from everyone before I start writing a complicated automated script for the plugin translations. Lisa Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat
Re: [Input request] Rethinking Plugin docs
On Feb 24, 2014, at 12:32 PM, Andrew Grieve agri...@chromium.org wrote: - We may also want to include README.md files in the translations. doc/fr/index.md doc/fr/README.md What content do you forsee being in README.md other than a table-of-contents to the languages? Or in other words, would it be public-facing content that could be collapsed in to the rest of the plugin docs? - We don't need the version in the directory since we can use git tags to find old versions That makes sense.
Re: [Input request] Rethinking Plugin docs
On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard cmarc...@gmail.com wrote: On Feb 24, 2014, at 12:32 PM, Andrew Grieve agri...@chromium.org wrote: - We may also want to include README.md files in the translations. doc/fr/index.md doc/fr/README.md What content do you forsee being in README.md other than a table-of-contents to the languages? Or in other words, would it be public-facing content that could be collapsed in to the rest of the plugin docs? On npmjs.org and on github, README.md's are the files that are shown most prominently. So, I speculate that many plugins will not provide a doc/ index.md, and instead provide only a README.md. - We don't need the version in the directory since we can use git tags to find old versions That makes sense.
Re: [Input request] Rethinking Plugin docs
If README.md is the standard why not just call all of them README and not have an index.md file at all for the plugins. What is the advantage of having both? Seems more confusing than anything. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | ldel...@apache.org | | ldel...@us.ibm.com | lisaseacat.com | | From: Andrew Grieve agri...@chromium.org To: dev dev@cordova.apache.org Date: 02/24/2014 01:41 PM Subject:Re: [Input request] Rethinking Plugin docs Sent by:agri...@google.com On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard cmarc...@gmail.com wrote: On Feb 24, 2014, at 12:32 PM, Andrew Grieve agri...@chromium.org wrote: - We may also want to include README.md files in the translations. doc/fr/index.md doc/fr/README.md What content do you forsee being in README.md other than a table-of-contents to the languages? Or in other words, would it be public-facing content that could be collapsed in to the rest of the plugin docs? On npmjs.org and on github, README.md's are the files that are shown most prominently. So, I speculate that many plugins will not provide a doc/ index.md, and instead provide only a README.md. - We don't need the version in the directory since we can use git tags to find old versions That makes sense.
Re: [Input request] Rethinking Plugin docs
That was basically the question in my head as I was typing... I'd be happy with having just a README.md, and allowing it to link to relative .md paths if it wanted to. On Mon, Feb 24, 2014 at 2:21 PM, Lisa Seacat DeLuca ldel...@us.ibm.comwrote: If README.md is the standard why not just call all of them README and not have an index.md file at all for the plugins. What is the advantage of having both? Seems more confusing than anything. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org*ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com*http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin]http://www.linkedin.com/in/lisaseacat From:Andrew Grieve agri...@chromium.org To:dev dev@cordova.apache.org Date:02/24/2014 01:41 PM Subject:Re: [Input request] Rethinking Plugin docs Sent by:agri...@google.com -- On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard cmarc...@gmail.com wrote: On Feb 24, 2014, at 12:32 PM, Andrew Grieve agri...@chromium.org wrote: - We may also want to include README.md files in the translations. doc/fr/index.md doc/fr/README.md What content do you forsee being in README.md other than a table-of-contents to the languages? Or in other words, would it be public-facing content that could be collapsed in to the rest of the plugin docs? On npmjs.org and on github, README.md's are the files that are shown most prominently. So, I speculate that many plugins will not provide a doc/ index.md, and instead provide only a README.md. - We don't need the version in the directory since we can use git tags to find old versions That makes sense.
Re: [Input request] Rethinking Plugin docs
I think Mike Brooks has extensive thinking wrt to this. Wait for his reply! On Mon, Feb 24, 2014 at 11:21 AM, Lisa Seacat DeLuca ldel...@us.ibm.comwrote: If README.md is the standard why not just call all of them README and not have an index.md file at all for the plugins. What is the advantage of having both? Seems more confusing than anything. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org*ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com*http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin]http://www.linkedin.com/in/lisaseacat From:Andrew Grieve agri...@chromium.org To:dev dev@cordova.apache.org Date:02/24/2014 01:41 PM Subject:Re: [Input request] Rethinking Plugin docs Sent by:agri...@google.com -- On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard cmarc...@gmail.com wrote: On Feb 24, 2014, at 12:32 PM, Andrew Grieve agri...@chromium.org wrote: - We may also want to include README.md files in the translations. doc/fr/index.md doc/fr/README.md What content do you forsee being in README.md other than a table-of-contents to the languages? Or in other words, would it be public-facing content that could be collapsed in to the rest of the plugin docs? On npmjs.org and on github, README.md's are the files that are shown most prominently. So, I speculate that many plugins will not provide a doc/ index.md, and instead provide only a README.md. - We don't need the version in the directory since we can use git tags to find old versions That makes sense.
Re: [Input request] Rethinking Plugin docs
I think Mike's main consideration is that the README.md is a place for general project info (what it is, how to contribute, etc) whereas documentation, inc translations, should be in a dedicated space as standard convention so we can tool it. (Something like this: `doc/[lang]/index.md`.) On Mon, Feb 24, 2014 at 11:26 AM, Andrew Grieve agri...@google.com wrote: That was basically the question in my head as I was typing... I'd be happy with having just a README.md, and allowing it to link to relative .md paths if it wanted to. On Mon, Feb 24, 2014 at 2:21 PM, Lisa Seacat DeLuca ldel...@us.ibm.comwrote: If README.md is the standard why not just call all of them README and not have an index.md file at all for the plugins. What is the advantage of having both? Seems more confusing than anything. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org*ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com*http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin]http://www.linkedin.com/in/lisaseacat From:Andrew Grieve agri...@chromium.org To:dev dev@cordova.apache.org Date:02/24/2014 01:41 PM Subject:Re: [Input request] Rethinking Plugin docs Sent by:agri...@google.com -- On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard cmarc...@gmail.com wrote: On Feb 24, 2014, at 12:32 PM, Andrew Grieve agri...@chromium.org wrote: - We may also want to include README.md files in the translations. doc/fr/index.md doc/fr/README.md What content do you forsee being in README.md other than a table-of-contents to the languages? Or in other words, would it be public-facing content that could be collapsed in to the rest of the plugin docs? On npmjs.org and on github, README.md's are the files that are shown most prominently. So, I speculate that many plugins will not provide a doc/ index.md, and instead provide only a README.md. - We don't need the version in the directory since we can use git tags to find old versions That makes sense.
Re: [Input request] Rethinking Plugin docs
+Michael Might be helpful to write out expanded README.md files for our plugins. Right now, they just contain a title and a link to the docs: https://github.com/apache/cordova-plugin-file What it is is covered by the first paragraph of the docs already I think. How to contribute is pretty obvious for most github-hosted projects, but I don't think that would hurt as part of the documentation either. On Mon, Feb 24, 2014 at 2:37 PM, Brian LeRoux b...@brian.io wrote: I think Mike's main consideration is that the README.md is a place for general project info (what it is, how to contribute, etc) whereas documentation, inc translations, should be in a dedicated space as standard convention so we can tool it. (Something like this: `doc/[lang]/index.md `.) On Mon, Feb 24, 2014 at 11:26 AM, Andrew Grieve agri...@google.com wrote: That was basically the question in my head as I was typing... I'd be happy with having just a README.md, and allowing it to link to relative .md paths if it wanted to. On Mon, Feb 24, 2014 at 2:21 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: If README.md is the standard why not just call all of them README and not have an index.md file at all for the plugins. What is the advantage of having both? Seems more confusing than anything. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Andrew Grieve agri...@chromium.org To:dev dev@cordova.apache.org Date:02/24/2014 01:41 PM Subject:Re: [Input request] Rethinking Plugin docs Sent by:agri...@google.com -- On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard cmarc...@gmail.com wrote: On Feb 24, 2014, at 12:32 PM, Andrew Grieve agri...@chromium.org wrote: - We may also want to include README.md files in the translations. doc/fr/index.md doc/fr/README.md What content do you forsee being in README.md other than a table-of-contents to the languages? Or in other words, would it be public-facing content that could be collapsed in to the rest of the plugin docs? On npmjs.org and on github, README.md's are the files that are shown most prominently. So, I speculate that many plugins will not provide a doc/ index.md, and instead provide only a README.md. - We don't need the version in the directory since we can use git tags to find old versions That makes sense.
Re: [Input request] Rethinking Plugin docs
I personally think we should merge the two into README.md. Our readme files in the plugins are useless right now. Might as well combine some of the info that should be in the readme + index.md so we have all of the important information shown prominently. On Mon, Feb 24, 2014 at 11:53 AM, Andrew Grieve agri...@chromium.orgwrote: +Michael Might be helpful to write out expanded README.md files for our plugins. Right now, they just contain a title and a link to the docs: https://github.com/apache/cordova-plugin-file What it is is covered by the first paragraph of the docs already I think. How to contribute is pretty obvious for most github-hosted projects, but I don't think that would hurt as part of the documentation either. On Mon, Feb 24, 2014 at 2:37 PM, Brian LeRoux b...@brian.io wrote: I think Mike's main consideration is that the README.md is a place for general project info (what it is, how to contribute, etc) whereas documentation, inc translations, should be in a dedicated space as standard convention so we can tool it. (Something like this: `doc/[lang]/index.md `.) On Mon, Feb 24, 2014 at 11:26 AM, Andrew Grieve agri...@google.com wrote: That was basically the question in my head as I was typing... I'd be happy with having just a README.md, and allowing it to link to relative .md paths if it wanted to. On Mon, Feb 24, 2014 at 2:21 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: If README.md is the standard why not just call all of them README and not have an index.md file at all for the plugins. What is the advantage of having both? Seems more confusing than anything. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Andrew Grieve agri...@chromium.org To:dev dev@cordova.apache.org Date:02/24/2014 01:41 PM Subject:Re: [Input request] Rethinking Plugin docs Sent by:agri...@google.com -- On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard cmarc...@gmail.com wrote: On Feb 24, 2014, at 12:32 PM, Andrew Grieve agri...@chromium.org wrote: - We may also want to include README.md files in the translations. doc/fr/index.md doc/fr/README.md What content do you forsee being in README.md other than a table-of-contents to the languages? Or in other words, would it be public-facing content that could be collapsed in to the rest of the plugin docs? On npmjs.org and on github, README.md's are the files that are shown most prominently. So, I speculate that many plugins will not provide a doc/ index.md, and instead provide only a README.md. - We don't need the version in the directory since we can use git tags to find old versions That makes sense.
Re: [Input request] Rethinking Plugin docs
README.md merge +1 I understand the idea behind keeping the documentation outside of the README.md but given that the how to contribute and other info is generally the same across all of the plugins and is available on the wiki, etc. it's probably redundant to put it in each repo as well. That being said it probably wouldn't hurt to have a link on the top of the README.md's pointing back to the main cordova project info. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | ldel...@apache.org | | ldel...@us.ibm.com | lisaseacat.com | | From: Steven Gill stevengil...@gmail.com To: dev@cordova.apache.org dev@cordova.apache.org Cc: Lisa Seacat DeLuca/San Francisco/IBM@IBMUS, Michael Brooks mich...@michaelbrooks.ca Date: 02/24/2014 03:08 PM Subject:Re: [Input request] Rethinking Plugin docs I personally think we should merge the two into README.md. Our readme files in the plugins are useless right now. Might as well combine some of the info that should be in the readme + index.md so we have all of the important information shown prominently. On Mon, Feb 24, 2014 at 11:53 AM, Andrew Grieve agri...@chromium.orgwrote: +Michael Might be helpful to write out expanded README.md files for our plugins. Right now, they just contain a title and a link to the docs: https://github.com/apache/cordova-plugin-file What it is is covered by the first paragraph of the docs already I think. How to contribute is pretty obvious for most github-hosted projects, but I don't think that would hurt as part of the documentation either. On Mon, Feb 24, 2014 at 2:37 PM, Brian LeRoux b...@brian.io wrote: I think Mike's main consideration is that the README.md is a place for general project info (what it is, how to contribute, etc) whereas documentation, inc translations, should be in a dedicated space as standard convention so we can tool it. (Something like this: `doc/[lang]/index.md `.) On Mon, Feb 24, 2014 at 11:26 AM, Andrew Grieve agri...@google.com wrote: That was basically the question in my head as I was typing... I'd be happy with having just a README.md, and allowing it to link to relative .md paths if it wanted to. On Mon, Feb 24, 2014 at 2:21 PM, Lisa Seacat DeLuca ldel...@us.ibm.com wrote: If README.md is the standard why not just call all of them README and not have an index.md file at all for the plugins. What is the advantage of having both? Seems more confusing than anything. Lisa Seacat DeLuca Mobile Engineer | t: +415.787.4589 | *ldel...@apache.org* ldel...@apache.org| | *ldel...@us.ibm.com* ldel...@us.ibm.com | *lisaseacat.com* http://www.lisaseacat.com/| [image: follow @LisaSeacat on twitter] http://www.twitter.com/LisaSeacat| [image: follow Lisa Seacat DeLuca on linkedin] http://www.linkedin.com/in/lisaseacat From:Andrew Grieve agri...@chromium.org To:dev dev@cordova.apache.org Date:02/24/2014 01:41 PM Subject:Re: [Input request] Rethinking Plugin docs Sent by:agri...@google.com -- On Mon, Feb 24, 2014 at 12:51 PM, Marcel Kinard cmarc...@gmail.com wrote: On Feb 24, 2014, at 12:32 PM, Andrew Grieve agri...@chromium.org wrote: - We may also want to include README.md files in the translations. doc/fr/index.md doc/fr/README.md What content do you forsee being in README.md other than a table-of-contents to the languages? Or in other words, would it be public-facing content that could be collapsed in to the rest of the plugin docs? On npmjs.org and on github, README.md's are the files that are shown most prominently. So, I speculate that many plugins will not provide a doc/ index.md, and instead provide only a README.md. - We don't need the version in the directory since we can use git tags to find old versions That makes sense.
