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.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 <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 >
