cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Brooks <mich...@michaelbrooks.ca>
Subject Re: Deleting Plugin Docs
Date Fri, 20 Dec 2013 21:00:16 GMT
>
> 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" <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 <john.wargo@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
> > > <csantana23@gmail.com>
> > >
> >
>

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