Hi Addy, My plan is for the core team is focus this week on tightening up our component set and fleshing out the docs and on-ramp materials. You're just a bit ahead of us. I hope to have clearer answers in a few days.
I'm leaning towards modifying our standard `index.html` to simply suggest you install `polymer-home-page` instead of redirecting you to an external site. WDYT? Scott On Mon, Feb 24, 2014 at 3:34 AM, Addy Osmani <[email protected]> wrote: > Hello Scott, > > Just picking up on this thread once again :) We are currently evaluating > how to prescribe best > practices around component documentation as part of WebComponents.org and > a Polymer > boilerplate project. > > The current setup you have based on <polymer-doc-viewer> and > <polymer-home-page> so far > work quite well, however I noticed that the source appears to rely on a > self-hosted endpoint: > > http://turbogadgetry.com/bowertopia/components/ > > If we were to model a way to auto-render docs using your setup today, > would calling the above > endpoint be feasible or would you prefer for us to (1) wait until a more > concrete docs approach has > been fleshed out or (2) a way to host this elsewhere (AppEngine?) so > others can use it without > causing issues. > > Cheers! > > > On Wed, Jan 29, 2014 at 6:03 PM, Addy Osmani <[email protected]> wrote: > >> Thanks for the walkthrough, Scott! I understand that much of this is >> proof-of-concept, but it's still highly useful. I'll take a look through >> your samples. >> >> >> On Wednesday, 29 January 2014 17:19:02 UTC, Scott Miles wrote: >> >>> For documentation, we have a system today that leverages YuiDoc tooling >>> and a context-free documentation syntax. The output we consume is a JSON >>> database, which can be rendered statically or on demand. >>> >>> An example of some rendered documentation can be seen here: >>> http://polymer.github.io/three-js/components/three-js/ >>> >>> The documentation renderer used is a component (polymer-doc-viewer) . >>> The default landing page (which includes the docs) is generated by another >>> component (polymer-home-page). >>> >>> Yes, the actual database is for `webaudio-knob` while the page is >>> supposed to be about `three-js`, that's just me being sloppy. I wasn't >>> planning on sharing these materials exactly today, but since it came up ... >>> =P >>> >>> Now, this example is a bit half-baked for a couple of reasons: (1) we >>> are evaluating other ways of generating docs, and (2) this is just a piece >>> of the larger meta-environment needed to support a rich component ecosystem. >>> >>> Our current thinking around this meta-system goes something like this >>> (cribbed from some other notes I have): >>> Goals >>> >>> - >>> >>> Decentralized (flexibility, decoupling, allow third-party innovation) >>> - >>> >>> Rich materials >>> - >>> >>> Low barrier to entry >>> - >>> >>> Free (support free server options) >>> - >>> >>> Easy to set up >>> >>> Leverage >>> >>> - >>> >>> Provide (optional) out-of-the-box solutions for docs, examples, >>> sandboxing (moar components!) >>> - >>> >>> Use free GitHub services >>> >>> Strawman: Requirements >>> >>> To participate in the ecosystem a component should have >>> >>> >>> - >>> >>> github repository >>> - >>> >>> landing (aka home or index or information) page >>> - >>> >>> demo page >>> >>> Component Identity >>> >>> A component can be identified as a URL that points to a metadata file. >>> The metadata (or the URL itself) identifies the github repository and the >>> dispensation of the landing and demo pages. >>> No Cost Setup >>> >>> Developer can set up live pages using GitHub servers by cloning the >>> component repository into a gh-pages branch (and including >>> dependencies; iow, clone working copy, bower install, push to >>> gh-pagesbranch). This set up requires no customization and can be automated. >>> >>> Example: three-js component installed to gh-pages: >>> >>> >>> landing page: >>> >>> http://polymer.github.io/three-js/components/three-js/ >>> >>> >>> demo page: >>> >>> http://polymer.github.io/three-js/components/three-js/demo.html >>> >>> (Links and content are variously messed up, these are just >>> proof-of-concept mocks.) >>> >>> >>> >>> On Wed, Jan 29, 2014 at 7:51 AM, Addy Osmani <[email protected]> wrote: >>> >>>> Picking up on this thread from last year: >>>> >>>> For a developer looking to document the elements they're authoring >>>> today, do we have an answer we can give them? (I've read through Eric's >>>> self-documenting proposal and agree, it's a beautiful vision). >>>> >>>> After playing around with the prototype, however it looks like we would >>>> need to either agree on an initial base template / format for the >>>> documentation element or punt to existing tools like JSDoc (which Eric has >>>> already mentioned has it's own issues as we're dealing with a multi-headed >>>> beast). >>>> >>>> I'm primarily interested in this for Polymer tooling/boilerplate >>>> projects where recommending documentation practices from the get-go would >>>> be super-useful. >>>> >>>> >>>> On Monday, 8 April 2013 20:02:19 UTC+1, Eric Bidelman wrote: >>>>> >>>>> Inspired by Mike K's great idea of self documenting custom elements, >>>>> I've written a proposal to formalize the effort. >>>>> We have a great opportunity here to come up with best practices early >>>>> on. >>>>> >>>>> *Proposal: Self Documenting Custom Elements <http://goo.gl/X5DxO>* >>>>> - prototype <http://goo.gl/0pdSW> - a custom element that uses >>>>> this method. >>>>> - it's <wc-documentation> <http://goo.gl/qzW7P> (best viewed in >>>>> Chrome Canary to get ::distributed()). >>>>> >>>>> [image: Inline image 1] >>>>> >>>>> Things I like about this approach: >>>>> >>>>> - The delivery mechanism is <link rel="import">. >>>>> - Becomes the "view source of custom elements". Click an import's link >>>>> -> get its docs. >>>>> - The docs themselves are custom elements >>>>> - works reasonably well in other modern browsers, especially if the >>>>> toolkit polyfills are included. >>>>> >>>>> Looking for everyone's feedback. >>>>> >>>>> Eric Bidelman >>>>> >>>> Follow Polymer on Google+: plus.google.com/107187849809354688692 >>>> --- >>>> You received this message because you are subscribed to the Google >>>> Groups "Polymer" group. >>>> To unsubscribe from this group and stop receiving emails from it, send >>>> an email to [email protected]. >>>> >>>> To view this discussion on the web visit https://groups.google.com/d/ >>>> msgid/polymer-dev/75b0e259-cd73-4806-b6ee-00cd7b1b7a17% >>>> 40googlegroups.com. >>>> >>>> For more options, visit https://groups.google.com/groups/opt_out. >>>> >>> >>> > Follow Polymer on Google+: plus.google.com/107187849809354688692 > --- > You received this message because you are subscribed to the Google Groups > "Polymer" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To view this discussion on the web visit > https://groups.google.com/d/msgid/polymer-dev/CAAKPnK8ce1bDtSZG0W0RWiQMiz5CfkdWuzmRKuwtzdNNsZE03Q%40mail.gmail.com > . > > For more options, visit https://groups.google.com/groups/opt_out. > Follow Polymer on Google+: plus.google.com/107187849809354688692 --- You received this message because you are subscribed to the Google Groups "Polymer" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/CAHbmOLbND3RpoYW1wbH6d6UoqcVA_am1YP%2BDVS6q%3DRWD6bQaag%40mail.gmail.com. For more options, visit https://groups.google.com/groups/opt_out.
