You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by Andrew Grieve <ag...@chromium.org> on 2013/12/13 19:33:27 UTC
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
Posted by Steven Gill <st...@gmail.com>.
love the idea.
On Dec 13, 2013 3:24 PM, "Shazron" <sh...@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 <
> michael@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 <agrieve@chromium.org
> >
> > > > wrote:
> > > >
> > > > > On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny <mmocny@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 <
> mmocny@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.billau@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
Posted by Shazron <sh...@gmail.com>.
+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 <michael@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 <ag...@chromium.org>
> > > wrote:
> > >
> > > > On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny <mm...@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 <mmocny@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.billau@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
Posted by Brian LeRoux <b...@brian.io>.
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 <mi...@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 <ag...@chromium.org>
> > wrote:
> >
> > > On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny <mm...@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 <mm...@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.billau@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
Posted by Brian LeRoux <b...@brian.io>.
Nope those remain. The baseline impl just basically webview+those events.
On Dec 24, 2013 4:41 AM, "Wargo, John" <jo...@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:csantana23@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 <jo...@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: agrieve@google.com [mailto:agrieve@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
> <cs...@gmail.com>
>
Re: Deleting Plugin Docs
Posted by Andrew Grieve <ag...@chromium.org>.
I've left them there:
http://cordova.apache.org/docs/en/edge/cordova_plugins_pluginapis.md.html#Plugin%20APIs
On Mon, Dec 23, 2013 at 1:33 PM, Wargo, John <jo...@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:csantana23@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 <jo...@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: agrieve@google.com [mailto:agrieve@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
> <cs...@gmail.com>
>
RE: Deleting Plugin Docs
Posted by "Wargo, John" <jo...@sap.com>.
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:csantana23@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 <jo...@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: agrieve@google.com [mailto:agrieve@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
<cs...@gmail.com>
Re: Deleting Plugin Docs
Posted by Brian LeRoux <b...@brian.io>.
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" <cs...@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 <csantana23@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 <agrieve@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 <csantana23@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 <jo...@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: agrieve@google.com [mailto:agrieve@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
> >> > <cs...@gmail.com>
> >> >
> >>
> >
> >
> >
> > --
> > Carlos Santana
> > <cs...@gmail.com>
> >
>
>
>
> --
> Carlos Santana
> <cs...@gmail.com>
>
Re: Deleting Plugin Docs
Posted by Carlos Santana <cs...@gmail.com>.
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 <cs...@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 <ag...@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 <csantana23@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 <jo...@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: agrieve@google.com [mailto:agrieve@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
>> > <cs...@gmail.com>
>> >
>>
>
>
>
> --
> Carlos Santana
> <cs...@gmail.com>
>
--
Carlos Santana
<cs...@gmail.com>
Re: Deleting Plugin Docs
Posted by Carlos Santana <cs...@gmail.com>.
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 <ag...@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 <csantana23@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 <jo...@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: agrieve@google.com [mailto:agrieve@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
> > <cs...@gmail.com>
> >
>
--
Carlos Santana
<cs...@gmail.com>
Re: Deleting Plugin Docs
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
>
> 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" <ag...@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 <csantana23@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 <jo...@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: agrieve@google.com [mailto:agrieve@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
> > > <cs...@gmail.com>
> > >
> >
>
Re: Deleting Plugin Docs
Posted by Brian LeRoux <b...@brian.io>.
Yes!
On Dec 21, 2013 2:50 AM, "Andrew Grieve" <ag...@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 <csantana23@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 <jo...@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: agrieve@google.com [mailto:agrieve@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
> > <cs...@gmail.com>
> >
>
Re: Deleting Plugin Docs
Posted by Andrew Grieve <ag...@chromium.org>.
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 <cs...@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 <jo...@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: agrieve@google.com [mailto:agrieve@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
> <cs...@gmail.com>
>
Re: Deleting Plugin Docs
Posted by Carlos Santana <cs...@gmail.com>.
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 <jo...@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: agrieve@google.com [mailto:agrieve@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
<cs...@gmail.com>
Re: Deleting Plugin Docs
Posted by Andrew Grieve <ag...@chromium.org>.
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 <jo...@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: agrieve@google.com [mailto:agrieve@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
Posted by "Wargo, John" <jo...@sap.com>.
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: agrieve@google.com [mailto:agrieve@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
Posted by Andrew Grieve <ag...@chromium.org>.
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 <cm...@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
Posted by Marcel Kinard <cm...@gmail.com>.
+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
Posted by Andrew Grieve <ag...@chromium.org>.
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 <mi...@michaelbrooks.ca>wrote:
> 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 <ag...@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
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
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 <ag...@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
Fwd: Deleting Plugin Docs
Posted by Andrew Grieve <ag...@chromium.org>.
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
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
> 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 <ag...@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 <cm...@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
Posted by Andrew Grieve <ag...@chromium.org>.
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 <cm...@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
Posted by Marcel Kinard <cm...@gmail.com>.
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
Posted by Michael Brooks <mi...@michaelbrooks.ca>.
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 <ag...@chromium.org>
> wrote:
>
> > On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny <mm...@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 <mm...@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.billau@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
Posted by Brian LeRoux <b...@brian.io>.
+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 <ag...@chromium.org> wrote:
> On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny <mm...@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 <mm...@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.billau@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
Posted by Andrew Grieve <ag...@chromium.org>.
On Fri, Dec 13, 2013 at 2:08 PM, Michal Mocny <mm...@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 <mm...@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.billau@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
Posted by Michal Mocny <mm...@chromium.org>.
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 <mm...@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 <mi...@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
Posted by Michal Mocny <mm...@chromium.org>.
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 <mi...@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
Posted by Mike Billau <mi...@gmail.com>.
>> 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.