RE: Deleting Plugin Docs
And what happen to features that aren't part of a plugin? Like the deviceready event, button events, application events for example? Those get lost if we do plugin-centric docs, right? John M. Wargo Twitter: @johnwargo -Original Message- From: Carlos Santana [mailto:csantan...@gmail.com] Sent: Friday, December 20, 2013 11:39 AM To: dev@cordova.apache.org Subject: Re: Deleting Plugin Docs I'm a bit lost Is the eventual goal to build the docs as a single website (docs.cordova.io) with multiple repos cordova-docs repo and plugin repos? On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John john.wa...@sap.com wrote: Andrew, Will you be processing the plugin docs so they generate the pages like they used to? Being able to click and link around within a particular plugin's doc is super helpful. John M. Wargo Twitter: @johnwargo -Original Message- From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew Grieve Sent: Wednesday, December 18, 2013 10:40 PM To: dev Subject: Fwd: Deleting Plugin Docs This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md -- Carlos Santana csantan...@gmail.com
RE: Deleting Plugin Docs
Nope those remain. The baseline impl just basically webview+those events. On Dec 24, 2013 4:41 AM, Wargo, John john.wa...@sap.com wrote: And what happen to features that aren't part of a plugin? Like the deviceready event, button events, application events for example? Those get lost if we do plugin-centric docs, right? John M. Wargo Twitter: @johnwargo -Original Message- From: Carlos Santana [mailto:csantan...@gmail.com] Sent: Friday, December 20, 2013 11:39 AM To: dev@cordova.apache.org Subject: Re: Deleting Plugin Docs I'm a bit lost Is the eventual goal to build the docs as a single website ( docs.cordova.io) with multiple repos cordova-docs repo and plugin repos? On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John john.wa...@sap.com wrote: Andrew, Will you be processing the plugin docs so they generate the pages like they used to? Being able to click and link around within a particular plugin's doc is super helpful. John M. Wargo Twitter: @johnwargo -Original Message- From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew Grieve Sent: Wednesday, December 18, 2013 10:40 PM To: dev Subject: Fwd: Deleting Plugin Docs This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md -- Carlos Santana csantan...@gmail.com
Re: Deleting Plugin Docs
Thanks! The problem I saw with the full examples, is that they are copy pastes of the Quick Examples, but put within an html page and an onDeviceReady callback. Given that the default app templates already have this, is it really necessary to have it in every example? You can still copy paste without having to replace your entire file. That said, maybe once we have our own plugins.cordova.io docs rendering engine, we could have examples auto-expand into full page examples via a button? Yeah, I now think it would be better to keep the File docs. The immediate problem with multiple files is that there's no way to do a side-nav with them hosted on github as .md files. Maybe we could have one file that just holds all of the examples, and another that's just the API spec? On Thu, Dec 19, 2013 at 4:00 PM, Michael Brooks mich...@michaelbrooks.cawrote: Nice Andrew. I think the Plugins API page is a good start. We can iterate on it to improve the experience. Personally, I would rather not have cut out the quick examples, full examples, etc. Some of the most positive feedback for our documentation is that it's thorough and copy paste ready. This helps to get people up and running quickly. Just my two cents. I am very hesitant about removing the File API documentation and linking to external sources. When files become too large - similar to functions - we use multiple files. In the past, we've found that the W3C spec or external documentation (e.g. File API used by certain browsers) is a moving target. How confident are we that the Cordova File API will be a 100% match to the HTML 5 Rocks documentation? Michael On Wed, Dec 18, 2013 at 7:39 PM, Andrew Grieve agri...@chromium.org wrote: This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md
Re: Deleting Plugin Docs
We'll point them to master as soon as the docs exist on master. On Thu, Dec 19, 2013 at 4:13 PM, Marcel Kinard cmarc...@gmail.com wrote: +1 to Michael's comments. And I know it is a bit too early to do this, but the links to the docs on github should point to the master branch, not the dev branch, correct? I don't think there is anything wrong with big docs, as long as they are useful and navigable.
RE: Deleting Plugin Docs
Andrew, Will you be processing the plugin docs so they generate the pages like they used to? Being able to click and link around within a particular plugin's doc is super helpful. John M. Wargo Twitter: @johnwargo -Original Message- From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew Grieve Sent: Wednesday, December 18, 2013 10:40 PM To: dev Subject: Fwd: Deleting Plugin Docs This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md
Re: Deleting Plugin Docs
I'm a bit lost Is the eventual goal to build the docs as a single website (docs.cordova.io) with multiple repos cordova-docs repo and plugin repos? On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John john.wa...@sap.com wrote: Andrew, Will you be processing the plugin docs so they generate the pages like they used to? Being able to click and link around within a particular plugin's doc is super helpful. John M. Wargo Twitter: @johnwargo -Original Message- From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew Grieve Sent: Wednesday, December 18, 2013 10:40 PM To: dev Subject: Fwd: Deleting Plugin Docs This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md -- Carlos Santana csantan...@gmail.com
Re: Deleting Plugin Docs
Not in the short-term. I think our docs should be easy enough to write such that all plugin authors take the time to do it. To me, that means simple .md files. Might be able to do more fancy things when we host on plugins.cordova.io, but for now, it's just github's .md formatting. On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John john.wa...@sap.com wrote: Andrew, Will you be processing the plugin docs so they generate the pages like they used to? Being able to click and link around within a particular plugin's doc is super helpful. John M. Wargo Twitter: @johnwargo -Original Message- From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew Grieve Sent: Wednesday, December 18, 2013 10:40 PM To: dev Subject: Fwd: Deleting Plugin Docs This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md
Re: Deleting Plugin Docs
The eventual goal (in my eyes) is to have plugin docs: 1. Appear with the plugins on plugins.cordova.io. 2. Be accessible to devs after they have installed the plugin (e.g. by looking at plugins/foo/doc, or maybe by having cordova serve show them) On Fri, Dec 20, 2013 at 11:38 AM, Carlos Santana csantan...@gmail.comwrote: I'm a bit lost Is the eventual goal to build the docs as a single website ( docs.cordova.io) with multiple repos cordova-docs repo and plugin repos? On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John john.wa...@sap.com wrote: Andrew, Will you be processing the plugin docs so they generate the pages like they used to? Being able to click and link around within a particular plugin's doc is super helpful. John M. Wargo Twitter: @johnwargo -Original Message- From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew Grieve Sent: Wednesday, December 18, 2013 10:40 PM To: dev Subject: Fwd: Deleting Plugin Docs This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md -- Carlos Santana csantan...@gmail.com
Re: Deleting Plugin Docs
All docs for Cordova CLI, Plugman CLI, and Platforms hosted/rendered on docs.cordova.io and All docs for Plugins hosted/rendered on plugins.cordova.io If this is true, I would like to see consistencies on look and feel of both websites, and ability to link back and forth between sites via links. On Fri, Dec 20, 2013 at 11:42 AM, Andrew Grieve agri...@chromium.orgwrote: The eventual goal (in my eyes) is to have plugin docs: 1. Appear with the plugins on plugins.cordova.io. 2. Be accessible to devs after they have installed the plugin (e.g. by looking at plugins/foo/doc, or maybe by having cordova serve show them) On Fri, Dec 20, 2013 at 11:38 AM, Carlos Santana csantan...@gmail.com wrote: I'm a bit lost Is the eventual goal to build the docs as a single website ( docs.cordova.io) with multiple repos cordova-docs repo and plugin repos? On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John john.wa...@sap.com wrote: Andrew, Will you be processing the plugin docs so they generate the pages like they used to? Being able to click and link around within a particular plugin's doc is super helpful. John M. Wargo Twitter: @johnwargo -Original Message- From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew Grieve Sent: Wednesday, December 18, 2013 10:40 PM To: dev Subject: Fwd: Deleting Plugin Docs This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md -- Carlos Santana csantan...@gmail.com -- Carlos Santana csantan...@gmail.com
Re: Deleting Plugin Docs
Agreed, that is a goal. Mike is looking at Docs, Joni/Steve/Anis Plugins, and we can refresh WWW last. On Dec 21, 2013 3:05 AM, Carlos Santana csantan...@gmail.com wrote: Forgot to mentioned consistency look and feel (i.e. CSS) between the *three*primary websites ! www.cordova.io docs.cordova.io plugins.cordova.io On Fri, Dec 20, 2013 at 11:52 AM, Carlos Santana csantan...@gmail.com wrote: All docs for Cordova CLI, Plugman CLI, and Platforms hosted/rendered on docs.cordova.io and All docs for Plugins hosted/rendered on plugins.cordova.io If this is true, I would like to see consistencies on look and feel of both websites, and ability to link back and forth between sites via links. On Fri, Dec 20, 2013 at 11:42 AM, Andrew Grieve agri...@chromium.org wrote: The eventual goal (in my eyes) is to have plugin docs: 1. Appear with the plugins on plugins.cordova.io. 2. Be accessible to devs after they have installed the plugin (e.g. by looking at plugins/foo/doc, or maybe by having cordova serve show them) On Fri, Dec 20, 2013 at 11:38 AM, Carlos Santana csantan...@gmail.com wrote: I'm a bit lost Is the eventual goal to build the docs as a single website ( docs.cordova.io) with multiple repos cordova-docs repo and plugin repos? On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John john.wa...@sap.com wrote: Andrew, Will you be processing the plugin docs so they generate the pages like they used to? Being able to click and link around within a particular plugin's doc is super helpful. John M. Wargo Twitter: @johnwargo -Original Message- From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew Grieve Sent: Wednesday, December 18, 2013 10:40 PM To: dev Subject: Fwd: Deleting Plugin Docs This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md -- Carlos Santana csantan...@gmail.com -- Carlos Santana csantan...@gmail.com -- Carlos Santana csantan...@gmail.com
Re: Deleting Plugin Docs
Yes! On Dec 21, 2013 2:50 AM, Andrew Grieve agri...@chromium.org wrote: The eventual goal (in my eyes) is to have plugin docs: 1. Appear with the plugins on plugins.cordova.io. 2. Be accessible to devs after they have installed the plugin (e.g. by looking at plugins/foo/doc, or maybe by having cordova serve show them) On Fri, Dec 20, 2013 at 11:38 AM, Carlos Santana csantan...@gmail.com wrote: I'm a bit lost Is the eventual goal to build the docs as a single website ( docs.cordova.io) with multiple repos cordova-docs repo and plugin repos? On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John john.wa...@sap.com wrote: Andrew, Will you be processing the plugin docs so they generate the pages like they used to? Being able to click and link around within a particular plugin's doc is super helpful. John M. Wargo Twitter: @johnwargo -Original Message- From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew Grieve Sent: Wednesday, December 18, 2013 10:40 PM To: dev Subject: Fwd: Deleting Plugin Docs This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md -- Carlos Santana csantan...@gmail.com
Re: Deleting Plugin Docs
The problem I saw with the full examples, is that they are copy pastes of the Quick Examples, but put within an html page and an onDeviceReady callback. Given that the default app templates already have this, is it really necessary to have it in every example? You can still copy paste without having to replace your entire file. That said, maybe once we have our own plugins.cordova.io docs rendering engine, we could have examples auto-expand into full page examples via a button? Yea, as Andrew concluded long file examples can always be hidden with a little CSS to expand and contract. In the long-run, I would like to see Full Examples live outside of the documentation in the directory: /plugin-name/example/name/index.html The documentation website can fetch these examples to display, but users can also run the examples whenever a plugin in downloaded, cloned, or installed. I think this adds more value to the Full Examples and makes them easier to maintain since they are runnable beyond copy paste. Forgot to mentioned consistency look and feel (i.e. CSS) between the *three*primary websites ! www.cordova.io docs.cordova.io plugins.cordova.io In the long-run, I'd like to see http://plugins.cordova.io host the plugin documentation. It should have a rich navigation that supports multiple doc file and multiple versions. This allows ALL plugins to have rich documentation generated from .md files - not just the official APIs. By making documentation simple, we should be able to encourage users to write docs for their own plugins. As Carlos mentioned, the looks feel of docs.cordova.io and docs on plugins.cordova.io should be a seamless design experience. Rad discussion guys! Michael On Fri, Dec 20, 2013 at 11:16 AM, Brian LeRoux b...@brian.io wrote: Yes! On Dec 21, 2013 2:50 AM, Andrew Grieve agri...@chromium.org wrote: The eventual goal (in my eyes) is to have plugin docs: 1. Appear with the plugins on plugins.cordova.io. 2. Be accessible to devs after they have installed the plugin (e.g. by looking at plugins/foo/doc, or maybe by having cordova serve show them) On Fri, Dec 20, 2013 at 11:38 AM, Carlos Santana csantan...@gmail.com wrote: I'm a bit lost Is the eventual goal to build the docs as a single website ( docs.cordova.io) with multiple repos cordova-docs repo and plugin repos? On Fri, Dec 20, 2013 at 11:00 AM, Wargo, John john.wa...@sap.com wrote: Andrew, Will you be processing the plugin docs so they generate the pages like they used to? Being able to click and link around within a particular plugin's doc is super helpful. John M. Wargo Twitter: @johnwargo -Original Message- From: agri...@google.com [mailto:agri...@google.com] On Behalf Of Andrew Grieve Sent: Wednesday, December 18, 2013 10:40 PM To: dev Subject: Fwd: Deleting Plugin Docs This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md -- Carlos Santana csantan...@gmail.com
Re: Deleting Plugin Docs
Nice Andrew. I think the Plugins API page is a good start. We can iterate on it to improve the experience. Personally, I would rather not have cut out the quick examples, full examples, etc. Some of the most positive feedback for our documentation is that it's thorough and copy paste ready. This helps to get people up and running quickly. Just my two cents. I am very hesitant about removing the File API documentation and linking to external sources. When files become too large - similar to functions - we use multiple files. In the past, we've found that the W3C spec or external documentation (e.g. File API used by certain browsers) is a moving target. How confident are we that the Cordova File API will be a 100% match to the HTML 5 Rocks documentation? Michael On Wed, Dec 18, 2013 at 7:39 PM, Andrew Grieve agri...@chromium.org wrote: This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md
Re: Deleting Plugin Docs
+1 to Michael's comments. And I know it is a bit too early to do this, but the links to the docs on github should point to the master branch, not the dev branch, correct? I don't think there is anything wrong with big docs, as long as they are useful and navigable.
Fwd: Deleting Plugin Docs
This is now done! Woo! No more having plugins code separate from their docs (I hear we might even get tests to live within plugin repos in the next while too!). I tried to be diligent, but it's possible I made mistakes along the way. You can see the result on the edge version of the docs: http://cordova.apache.org/docs/en/edge/ There's a new Plugins API page, and all of the plugin docs are moved into the respective repos within a doc/index.md file. Some of doc/index.md files are fairly large, and to help with that I attempted to remove some of the repetition that I found: Quick Examples vs. Full Examples, Overviews vs Descriptions (in cases where they were saying the same thing). Also - for the file API, I just wrote to refer to the FileSystem spec for the API and copied over only the Cordova platform quirks. This will be a bad offline experience, so I'm not 100% convinced that was the right thing to do, but wow is that file big if you were to copy over all of the documentation! https://github.com/apache/cordova-plugin-file/blob/dev/doc/index.md
Re: Deleting Plugin Docs
Michael - Just to clarify, you're suggesting that we put all docs-related files *except* the main README.md within docs/? This plays well with github, but wanted to clarify. Maybe translations can one day go in docs_translated/$LANGUAGE ## project-name/README.md The file should be targeted at contributors. It can describe the project structure, dependencies, issue tracker location, etc. It should refer all users to doc/index.md. ## project-name/doc/index.md The directory should be singular, unless the other root directories are plural (bins, libs, tests, specs, etc). This contains usage information for developers using the project as a binary or library. It can contain multiple files, but there should be an index.md to indicate the starting point. This following the web convention of index.html - if you have the urge to suggest main.md or project-name.md, then please take a moment to reflect on the early web with it's attempt at main.html. Index won. All docs go in the doc/ directory. Translated docs would likewise go under doc/, not docs-translated/. We can decide on whatever convention we wish for with the translated documentation. Either doc/lang/ or doc/i8n/lang/ would make sense to me. In the case of doc/i8n/ we can make English the default at doc/content/, which would allow for easy HTML navigation since there would be a meaningful index.html in the root. ## Filename letter case preservation Use a hypen ( - ). Not an underscore ( _ ) and not camel-case (CamelCase). This is the UNIX convention [1] and we are following the Unix convention for all other directory names (bin, lib, src, www, etc). ## Displaying the Docs In the short-term, we can point to the GitHub rendered files. However, that puts us at the whim of Apache's ability to keep GitHub mirroring alive. In the long run, I'd rather see plugins.cordova.io supporting rendering and navigating the content of doc/. [1] http://en.wikipedia.org/wiki/Filename#Letter_case_preservation On Mon, Dec 16, 2013 at 1:22 PM, Andrew Grieve agri...@chromium.org wrote: Issue created: https://issues.apache.org/jira/browse/CB-5658 Brian - no need to align this with plugins.cordova.io release. Until then, we can point at the github renderings of the READMEs Michael - Just to clarify, you're suggesting that we put all docs-related files *except* the main README.md within docs/? This plays well with github, but wanted to clarify. Maybe translations can one day go in docs_translated/$LANGUAGE Brian - does raise the query: should plugin install automate config.xml tags? Not sure what your asking... Marcel - Definitely. On Sat, Dec 14, 2013 at 6:59 AM, Marcel Kinard cmarc...@gmail.com wrote: SGTM. And where the plugin docs are removed from cordova-docs, there should be instructions on where consumers can find the relocated plugin docs.
Re: Deleting Plugin Docs
Issue created: https://issues.apache.org/jira/browse/CB-5658 Brian - no need to align this with plugins.cordova.io release. Until then, we can point at the github renderings of the READMEs Michael - Just to clarify, you're suggesting that we put all docs-related files *except* the main README.md within docs/? This plays well with github, but wanted to clarify. Maybe translations can one day go in docs_translated/$LANGUAGE Brian - does raise the query: should plugin install automate config.xml tags? Not sure what your asking... Marcel - Definitely. On Sat, Dec 14, 2013 at 6:59 AM, Marcel Kinard cmarc...@gmail.com wrote: SGTM. And where the plugin docs are removed from cordova-docs, there should be instructions on where consumers can find the relocated plugin docs.
Re: Deleting Plugin Docs
SGTM. And where the plugin docs are removed from cordova-docs, there should be instructions on where consumers can find the relocated plugin docs.
Deleting Plugin Docs
I would like to: 1. Delete the docs/ directory from all plugins - They contain stale copies of what's in cordova-docs 2. Move plugin information found in cordova-docs into a single README.md file within the respective plugin repos 3. Delete the API Reference section of cordova-docs 4. Add a guide called Cordova Plugins, which contains: - a link to plugins.cordova.io, - a list of the org.apache.cordova plugins, which link to their README.md files on github - e.g. https://github.com/apache/cordova-plugin-media-capture/blob/master/README.md - These can be changed to point at their plugins.cordova.io page when that shows READMEs. - A link to the 3.3 docs, which still have plugin API reference - Mostly, this is for finding non-english versions. Motivation: - Plugins are on a separate release cycle from platforms docs. - The documentation is often mismatched due to this - Pull requests for plugins don't update the plugin docs - But I think they would if the docs were in the same repo Caveats: - This will mess up our current translations story for plugins. - I think this can be fixed up though, by changing out http://crowdin.netpush / pull scripts - E.g. have README.md translations go in: cordova-plugin-foo/translations/fr/README.md I'll make a JIRA for this, but want buy-in first.
Re: Deleting Plugin Docs
2. Move plugin information found in cordova-docs into a single README.md file within the respective plugin repos And also remove the /cordova/ folder from cordova-docs, right? This way there will be only one single location for a plugin's documentation (the README.md file inside that plugin repo). What will we do for docs of older versions? If somebody is using 2.9, they will need the 2.9 README.md file - is it enough for them to just change the branch on github? Assuming that there is no problem with viewing older documentation, then +1 on all of these.
Re: Deleting Plugin Docs
Mike, actually I think with this proposal it should be easier than ever to match plugin to docs specific to its version. The documentation would come bundled with the plugin, so you can find the README.md alongside wherever your plugin code resides, be that an old download, a plugman install, or from a git repo locally. Andrew, this all sounds pretty good, but looking forward to seeing Michael Brooks/Brian chime in since I think they had a docs plan up their sleeve. Also, do we want to add a CLI command to show plugin docs? -Michal On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau mike.bil...@gmail.com wrote: 2. Move plugin information found in cordova-docs into a single README.md file within the respective plugin repos And also remove the /cordova/ folder from cordova-docs, right? This way there will be only one single location for a plugin's documentation (the README.md file inside that plugin repo). What will we do for docs of older versions? If somebody is using 2.9, they will need the 2.9 README.md file - is it enough for them to just change the branch on github? Assuming that there is no problem with viewing older documentation, then +1 on all of these.
Re: Deleting Plugin Docs
RE my last suggest about CLI command for plugin docs, I'm now thinking it would be better to do something like we plan for tests: ship an app that hosts the docs based on whichever plugins you have installed. Perhaps the test app should even do both tasks? On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny mmo...@chromium.org wrote: Mike, actually I think with this proposal it should be easier than ever to match plugin to docs specific to its version. The documentation would come bundled with the plugin, so you can find the README.md alongside wherever your plugin code resides, be that an old download, a plugman install, or from a git repo locally. Andrew, this all sounds pretty good, but looking forward to seeing Michael Brooks/Brian chime in since I think they had a docs plan up their sleeve. Also, do we want to add a CLI command to show plugin docs? -Michal On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau mike.bil...@gmail.comwrote: 2. Move plugin information found in cordova-docs into a single README.md file within the respective plugin repos And also remove the /cordova/ folder from cordova-docs, right? This way there will be only one single location for a plugin's documentation (the README.md file inside that plugin repo). What will we do for docs of older versions? If somebody is using 2.9, they will need the 2.9 README.md file - is it enough for them to just change the branch on github? Assuming that there is no problem with viewing older documentation, then +1 on all of these.
Re: Deleting Plugin Docs
On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny mmo...@chromium.org wrote: RE my last suggest about CLI command for plugin docs, I'm now thinking it would be better to do something like we plan for tests: ship an app that hosts the docs based on whichever plugins you have installed. Perhaps the test app should even do both tasks? I think it'd be fine to think about this as a do-later thing, but I don't want to get side-tracked just yet with these kinds of possibilities. On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny mmo...@chromium.org wrote: Mike, actually I think with this proposal it should be easier than ever to match plugin to docs specific to its version. The documentation would come bundled with the plugin, so you can find the README.md alongside wherever your plugin code resides, be that an old download, a plugman install, or from a git repo locally. Andrew, this all sounds pretty good, but looking forward to seeing Michael Brooks/Brian chime in since I think they had a docs plan up their sleeve. Also, do we want to add a CLI command to show plugin docs? -Michal On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau mike.bil...@gmail.com wrote: 2. Move plugin information found in cordova-docs into a single README.md file within the respective plugin repos And also remove the /cordova/ folder from cordova-docs, right? This way there will be only one single location for a plugin's documentation (the README.md file inside that plugin repo). Right. The goal is one spot for plugin docs. What will we do for docs of older versions? If somebody is using 2.9, they will need the 2.9 README.md file - is it enough for them to just change the branch on github? This change will not affect publish docs for older versions. for 2.9, you'd still go to docs.cordova.io's 2.9 documentation. Assuming that there is no problem with viewing older documentation, then +1 on all of these.
Re: Deleting Plugin Docs
+1 (we should time this for the plugins.cordova.io refactor/release so we don't have a period of zero published plugin documentation) On Sat, Dec 14, 2013 at 6:47 AM, Andrew Grieve agri...@chromium.org wrote: On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny mmo...@chromium.org wrote: RE my last suggest about CLI command for plugin docs, I'm now thinking it would be better to do something like we plan for tests: ship an app that hosts the docs based on whichever plugins you have installed. Perhaps the test app should even do both tasks? I think it'd be fine to think about this as a do-later thing, but I don't want to get side-tracked just yet with these kinds of possibilities. On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny mmo...@chromium.org wrote: Mike, actually I think with this proposal it should be easier than ever to match plugin to docs specific to its version. The documentation would come bundled with the plugin, so you can find the README.md alongside wherever your plugin code resides, be that an old download, a plugman install, or from a git repo locally. Andrew, this all sounds pretty good, but looking forward to seeing Michael Brooks/Brian chime in since I think they had a docs plan up their sleeve. Also, do we want to add a CLI command to show plugin docs? -Michal On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau mike.bil...@gmail.com wrote: 2. Move plugin information found in cordova-docs into a single README.md file within the respective plugin repos And also remove the /cordova/ folder from cordova-docs, right? This way there will be only one single location for a plugin's documentation (the README.md file inside that plugin repo). Right. The goal is one spot for plugin docs. What will we do for docs of older versions? If somebody is using 2.9, they will need the 2.9 README.md file - is it enough for them to just change the branch on github? This change will not affect publish docs for older versions. for 2.9, you'd still go to docs.cordova.io's 2.9 documentation. Assuming that there is no problem with viewing older documentation, then +1 on all of these.
Re: Deleting Plugin Docs
Hi Andrew, I like this plan. It aligns perfectly with where I want the docs to go. I would rather see each plugin use a doc/index.md file for the API documentation. However, since plugins.cordova.io should auto-generate the README.md to HTML, it makes sense to use that file instead. However, I would like to see any assets (images) or additional markdown files placed in the doc/ directory. Thanks for taking the lead on this one, Michael On Fri, Dec 13, 2013 at 1:09 PM, Brian LeRoux b...@brian.io wrote: +1 (we should time this for the plugins.cordova.io refactor/release so we don't have a period of zero published plugin documentation) On Sat, Dec 14, 2013 at 6:47 AM, Andrew Grieve agri...@chromium.org wrote: On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny mmo...@chromium.org wrote: RE my last suggest about CLI command for plugin docs, I'm now thinking it would be better to do something like we plan for tests: ship an app that hosts the docs based on whichever plugins you have installed. Perhaps the test app should even do both tasks? I think it'd be fine to think about this as a do-later thing, but I don't want to get side-tracked just yet with these kinds of possibilities. On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny mmo...@chromium.org wrote: Mike, actually I think with this proposal it should be easier than ever to match plugin to docs specific to its version. The documentation would come bundled with the plugin, so you can find the README.md alongside wherever your plugin code resides, be that an old download, a plugman install, or from a git repo locally. Andrew, this all sounds pretty good, but looking forward to seeing Michael Brooks/Brian chime in since I think they had a docs plan up their sleeve. Also, do we want to add a CLI command to show plugin docs? -Michal On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau mike.bil...@gmail.com wrote: 2. Move plugin information found in cordova-docs into a single README.md file within the respective plugin repos And also remove the /cordova/ folder from cordova-docs, right? This way there will be only one single location for a plugin's documentation (the README.md file inside that plugin repo). Right. The goal is one spot for plugin docs. What will we do for docs of older versions? If somebody is using 2.9, they will need the 2.9 README.md file - is it enough for them to just change the branch on github? This change will not affect publish docs for older versions. for 2.9, you'd still go to docs.cordova.io's 2.9 documentation. Assuming that there is no problem with viewing older documentation, then +1 on all of these.
Re: Deleting Plugin Docs
ya I like that plan too README should just be simple description of what it is and how to install does raise the query: should plugin install automate config.xml tags? On Sat, Dec 14, 2013 at 8:22 AM, Michael Brooks mich...@michaelbrooks.cawrote: Hi Andrew, I like this plan. It aligns perfectly with where I want the docs to go. I would rather see each plugin use a doc/index.md file for the API documentation. However, since plugins.cordova.io should auto-generate the README.md to HTML, it makes sense to use that file instead. However, I would like to see any assets (images) or additional markdown files placed in the doc/ directory. Thanks for taking the lead on this one, Michael On Fri, Dec 13, 2013 at 1:09 PM, Brian LeRoux b...@brian.io wrote: +1 (we should time this for the plugins.cordova.io refactor/release so we don't have a period of zero published plugin documentation) On Sat, Dec 14, 2013 at 6:47 AM, Andrew Grieve agri...@chromium.org wrote: On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny mmo...@chromium.org wrote: RE my last suggest about CLI command for plugin docs, I'm now thinking it would be better to do something like we plan for tests: ship an app that hosts the docs based on whichever plugins you have installed. Perhaps the test app should even do both tasks? I think it'd be fine to think about this as a do-later thing, but I don't want to get side-tracked just yet with these kinds of possibilities. On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny mmo...@chromium.org wrote: Mike, actually I think with this proposal it should be easier than ever to match plugin to docs specific to its version. The documentation would come bundled with the plugin, so you can find the README.md alongside wherever your plugin code resides, be that an old download, a plugman install, or from a git repo locally. Andrew, this all sounds pretty good, but looking forward to seeing Michael Brooks/Brian chime in since I think they had a docs plan up their sleeve. Also, do we want to add a CLI command to show plugin docs? -Michal On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau mike.bil...@gmail.com wrote: 2. Move plugin information found in cordova-docs into a single README.md file within the respective plugin repos And also remove the /cordova/ folder from cordova-docs, right? This way there will be only one single location for a plugin's documentation (the README.md file inside that plugin repo). Right. The goal is one spot for plugin docs. What will we do for docs of older versions? If somebody is using 2.9, they will need the 2.9 README.md file - is it enough for them to just change the branch on github? This change will not affect publish docs for older versions. for 2.9, you'd still go to docs.cordova.io's 2.9 documentation. Assuming that there is no problem with viewing older documentation, then +1 on all of these.
Re: Deleting Plugin Docs
+1 from me, makes sense On Fri, Dec 13, 2013 at 2:07 PM, Brian LeRoux b...@brian.io wrote: ya I like that plan too README should just be simple description of what it is and how to install does raise the query: should plugin install automate config.xml tags? On Sat, Dec 14, 2013 at 8:22 AM, Michael Brooks mich...@michaelbrooks.ca wrote: Hi Andrew, I like this plan. It aligns perfectly with where I want the docs to go. I would rather see each plugin use a doc/index.md file for the API documentation. However, since plugins.cordova.io should auto-generate the README.md to HTML, it makes sense to use that file instead. However, I would like to see any assets (images) or additional markdown files placed in the doc/ directory. Thanks for taking the lead on this one, Michael On Fri, Dec 13, 2013 at 1:09 PM, Brian LeRoux b...@brian.io wrote: +1 (we should time this for the plugins.cordova.io refactor/release so we don't have a period of zero published plugin documentation) On Sat, Dec 14, 2013 at 6:47 AM, Andrew Grieve agri...@chromium.org wrote: On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny mmo...@chromium.org wrote: RE my last suggest about CLI command for plugin docs, I'm now thinking it would be better to do something like we plan for tests: ship an app that hosts the docs based on whichever plugins you have installed. Perhaps the test app should even do both tasks? I think it'd be fine to think about this as a do-later thing, but I don't want to get side-tracked just yet with these kinds of possibilities. On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny mmo...@chromium.org wrote: Mike, actually I think with this proposal it should be easier than ever to match plugin to docs specific to its version. The documentation would come bundled with the plugin, so you can find the README.md alongside wherever your plugin code resides, be that an old download, a plugman install, or from a git repo locally. Andrew, this all sounds pretty good, but looking forward to seeing Michael Brooks/Brian chime in since I think they had a docs plan up their sleeve. Also, do we want to add a CLI command to show plugin docs? -Michal On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau mike.bil...@gmail.com wrote: 2. Move plugin information found in cordova-docs into a single README.md file within the respective plugin repos And also remove the /cordova/ folder from cordova-docs, right? This way there will be only one single location for a plugin's documentation (the README.md file inside that plugin repo). Right. The goal is one spot for plugin docs. What will we do for docs of older versions? If somebody is using 2.9, they will need the 2.9 README.md file - is it enough for them to just change the branch on github? This change will not affect publish docs for older versions. for 2.9, you'd still go to docs.cordova.io's 2.9 documentation. Assuming that there is no problem with viewing older documentation, then +1 on all of these.
Re: Deleting Plugin Docs
love the idea. On Dec 13, 2013 3:24 PM, Shazron shaz...@gmail.com wrote: +1 from me, makes sense On Fri, Dec 13, 2013 at 2:07 PM, Brian LeRoux b...@brian.io wrote: ya I like that plan too README should just be simple description of what it is and how to install does raise the query: should plugin install automate config.xml tags? On Sat, Dec 14, 2013 at 8:22 AM, Michael Brooks mich...@michaelbrooks.ca wrote: Hi Andrew, I like this plan. It aligns perfectly with where I want the docs to go. I would rather see each plugin use a doc/index.md file for the API documentation. However, since plugins.cordova.io should auto-generate the README.md to HTML, it makes sense to use that file instead. However, I would like to see any assets (images) or additional markdown files placed in the doc/ directory. Thanks for taking the lead on this one, Michael On Fri, Dec 13, 2013 at 1:09 PM, Brian LeRoux b...@brian.io wrote: +1 (we should time this for the plugins.cordova.io refactor/release so we don't have a period of zero published plugin documentation) On Sat, Dec 14, 2013 at 6:47 AM, Andrew Grieve agri...@chromium.org wrote: On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny mmo...@chromium.org wrote: RE my last suggest about CLI command for plugin docs, I'm now thinking it would be better to do something like we plan for tests: ship an app that hosts the docs based on whichever plugins you have installed. Perhaps the test app should even do both tasks? I think it'd be fine to think about this as a do-later thing, but I don't want to get side-tracked just yet with these kinds of possibilities. On Fri, Dec 13, 2013 at 2:06 PM, Michal Mocny mmo...@chromium.org wrote: Mike, actually I think with this proposal it should be easier than ever to match plugin to docs specific to its version. The documentation would come bundled with the plugin, so you can find the README.md alongside wherever your plugin code resides, be that an old download, a plugman install, or from a git repo locally. Andrew, this all sounds pretty good, but looking forward to seeing Michael Brooks/Brian chime in since I think they had a docs plan up their sleeve. Also, do we want to add a CLI command to show plugin docs? -Michal On Fri, Dec 13, 2013 at 1:54 PM, Mike Billau mike.bil...@gmail.com wrote: 2. Move plugin information found in cordova-docs into a single README.md file within the respective plugin repos And also remove the /cordova/ folder from cordova-docs, right? This way there will be only one single location for a plugin's documentation (the README.md file inside that plugin repo). Right. The goal is one spot for plugin docs. What will we do for docs of older versions? If somebody is using 2.9, they will need the 2.9 README.md file - is it enough for them to just change the branch on github? This change will not affect publish docs for older versions. for 2.9, you'd still go to docs.cordova.io's 2.9 documentation. Assuming that there is no problem with viewing older documentation, then +1 on all of these.
