cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Grieve <agri...@chromium.org>
Subject Re: Deleting Plugin Docs
Date Fri, 20 Dec 2013 15:53:03 GMT
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 <michael@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 <agrieve@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
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message