I would absolutely <3 that. Being hosted on wc.org also makes it easier for us to encourage those writing elements with Brick/X-Tag/anything else to use the same docs strategy.
On Mon, Feb 24, 2014 at 6:05 PM, Eric Bidelman <[email protected]> wrote: > Being able to view live docs without having to install anything would be > *very* nice. > > What do we think about this: > webcomponents.org/docviewer?element=http://components-r-us.com/my-tag.html > > /docviewer would contain <polymer-doc-viewer> and render the docs for > my-tag.html (or whatever URL you pass it). Anyone that follows the > documentation practices (CORs enable their imports, uses YUIDoc comments, > etc) can use this. > > Thoughts? > > > On Mon, Feb 24, 2014 at 9:36 AM, Scott Miles <[email protected]> wrote: > >> 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. >> > > 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/CAAKPnK_KtiG-WS-5KFTnqH8z9UEoizf%3D4FWWGja9doCDN8-WBA%40mail.gmail.com. For more options, visit https://groups.google.com/groups/opt_out.
