vanishing documentation

[Joern Turner]

Hi Polymer team,

i noticed that more and more of the documentation for Polymer 2 Element is gone from webcomponents.org. That's really unlucky when you're still working with 2.0 (which we do for good reason). 

if i e.g. lookup app-route i can get 2 versions for Polymer3 but none for Polymer2. 

That means that essential information is missing when you need to change things or even start new apps on Polymer2. 

Is there some other location where Polymer 2 element docs are available? Please also consider a downloadable format for element docs. Would make live of a developer so much easier.

Thanks,

Joern

[John Teague]

Unfortunately, HTML Imports is deprecated, which makes long term use of Polymer 2 unworkable. So, migrating to Polymer 3 and ES modules fixes that, and with migrator tool, which admittedly isn't perfect, can speed that. The docs for polymer 2 are still in the polymer 2 site. I can't help with search performance, but I suspect the index is logically favoring Polymer 3, which are the most current docs.

[Joern Turner]

Am Donnerstag, 11. Oktober 2018 20:55:44 UTC+2 schrieb John Teague:

Unfortunately, HTML Imports is deprecated, which makes long term use of Polymer 2 unworkable. So, migrating to Polymer 3 and ES modules fixes that, and with migrator tool, which admittedly isn't perfect, can speed that. The docs for polymer 2 are still in the polymer 2 site. I can't help with search performance, but I suspect the index is logically favoring Polymer 3, which are the most current docs.

i know that html imports is deprecated but is that a reason to take documentation for 2.0 offline? I'm not talking about polymer-project.org but webcomponents.org where docs for version before 3.0 are missing.

I wonder for whom Polymer is built - for those that follows the last hype (seems so) or for those that build serious applications. These applications cannot always be migrated quickly to a newer version and furthermore economic reasons always play a major role. How shall i sell that to a customer: the new version does not bring much benefit (if at all) but we have to spent x days to migrate to the latest? Why just change if apps do well?

Furthermore we'll likely never migrate to Polymer3 which is a major step backwards in our opinion (lack of descriptive templates). We love webcomponents and Polymer 2 but the latest directions the spec went are a clear mistake - efficiency over architecture. It's a pitty that specs not always evolve in the right direction.

Sorry - but you hit that button in me again. It's pure frustration - i'm still hoping for HTML modules but certainly will never go with literal templates. That's simply rubbish - sorry again - it's not you i'm targetting.

[Justin Fagnani]

Hi Joern,

There's a "View Bower docs" link in the left-nav that will take you to the Bower-based package docs. Then you can choose 2.x versions from the version dropdown.

As for you other questions...

On Sat, Oct 13, 2018 at 5:24 AM Joern Turner <joern....@gmail.com> wrote:

Am Donnerstag, 11. Oktober 2018 20:55:44 UTC+2 schrieb John Teague:

Unfortunately, HTML Imports is deprecated, which makes long term use of Polymer 2 unworkable. So, migrating to Polymer 3 and ES modules fixes that, and with migrator tool, which admittedly isn't perfect, can speed that. The docs for polymer 2 are still in the polymer 2 site. I can't help with search performance, but I suspect the index is logically favoring Polymer 3, which are the most current docs.

i know that html imports is deprecated but is that a reason to take documentation for 2.0 offline? I'm not talking about polymer-project.org but webcomponents.org where docs for version before 3.0 are missing.

I wonder for whom Polymer is built - for those that follows the last hype (seems so) or for those that build serious applications.

Polymer is built to make Web Components easier to write. It's not about hype, but about reducing the boilerplate needed to make fast, high-quality Web Components with a great developer experience. We have customers that quite serious applications with Polymer and Web Components, like YouTube that was mentioned, and enterprise operations like large banks, publishers, and companies with dozens to hundreds of properties that they need to share components across.

 

These applications cannot always be migrated quickly to a newer version and furthermore economic reasons always play a major role. How shall i sell that to a customer: the new version does not bring much benefit (if at all)

Polymer 3 and Polymer 2 share their same code, and they offer the same benefits in terms of make Web Component authoring easier. The main benefit of Polymer 3 are

- It doesn't require any Polyfills on Safari, Firefox as of version 63, and soon Edge (they're implementing Web Components now).

- Polymer 3 elements are available on npm, and can have npm dependencies. Bower is deprecated and has very few packages compared to npm.

- Polymer 3 elements are importable into other JavaScript modules. There was no way to import Polymer 2 elements into JavaScript.

These are huge advantages.

 

but we have to spent x days to migrate to the latest? Why just change if apps do well?

Furthermore we'll likely never migrate to Polymer3 which is a major step backwards in our opinion (lack of descriptive templates). We love webcomponents and Polymer 2 but the latest directions the spec went are a clear mistake - efficiency over architecture. It's a pitty that specs not always evolve in the right direction.

The specs didn't change between Polymer 2 and 3. Yes, we stopped using HTML Imports, but HTML Imports were already not going to be implemented by other browsers. We simply stopped requiring a polyfill indefinitely.

 

Sorry - but you hit that button in me again. It's pure frustration - i'm still hoping for HTML modules but certainly will never go with literal templates. That's simply rubbish

Polymer 3 and Polymer 2 component implementations are essentially identical, we just have HTML-in-JS rather than JS-in-HTML. All the lines of code are basically the same. The change in container format doesn't fundamentally change the code you have to write, or the operations Polymer has to do to instantiate elements and render templates. It's really all the same code.

Sorry for your frustrations. We are trying to make Polymer simpler to use by aligning with current standards and tools. We can't be an island forever.

Cheers,

  Justin

 

- sorry again - it's not you i'm targetting.

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 polymer-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/d4a6fcd2-fe16-429a-b085-3895e706cd68%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Joern Turner]

Hi Justin,

Am Montag, 15. Oktober 2018 20:06:26 UTC+2 schrieb Justin Fagnani:

Hi Joern,

There's a "View Bower docs" link in the left-nav that will take you to the Bower-based package docs. Then you can choose 2.x versions from the version dropdown.

Ah, thanks for that - i actually didn't realize that.

 

As for you other questions...

On Sat, Oct 13, 2018 at 5:24 AM Joern Turner <joern....@gmail.com> wrote:

Am Donnerstag, 11. Oktober 2018 20:55:44 UTC+2 schrieb John Teague:

Unfortunately, HTML Imports is deprecated, which makes long term use of Polymer 2 unworkable. So, migrating to Polymer 3 and ES modules fixes that, and with migrator tool, which admittedly isn't perfect, can speed that. The docs for polymer 2 are still in the polymer 2 site. I can't help with search performance, but I suspect the index is logically favoring Polymer 3, which are the most current docs.

i know that html imports is deprecated but is that a reason to take documentation for 2.0 offline? I'm not talking about polymer-project.org but webcomponents.org where docs for version before 3.0 are missing.

I wonder for whom Polymer is built - for those that follows the last hype (seems so) or for those that build serious applications.

Polymer is built to make Web Components easier to write. It's not about hype, but about reducing the boilerplate needed to make fast, high-quality Web Components with a great developer experience. We have customers that quite serious applications with Polymer and Web Components, like YouTube that was mentioned, and enterprise operations like large banks, publishers, and companies with dozens to hundreds of properties that they need to share components across.

I didn't mean that Polymer is hype but the pressure to follow the latest version. Especially when it comes to serious applications you're often not able or rather conservative about upgrading once a new version is out. Also you find that the 'market' is not following as fast. E.g. there are thousands of Polymer 2 components and not all have a chance being upgraded quickly. Our projects also use third-party components and rely on these working seemlessly in a new version. This at least needs to be tested and takes some effort to do. When your project has hundreds of components you're cautious of saying 'ok, let's move to Polymer 3 tomorrow'.

 

 

These applications cannot always be migrated quickly to a newer version and furthermore economic reasons always play a major role. How shall i sell that to a customer: the new version does not bring much benefit (if at all)

Polymer 3 and Polymer 2 share their same code, and they offer the same benefits in terms of make Web Component authoring easier. The main benefit of Polymer 3 are

- It doesn't require any Polyfills on Safari, Firefox as of version 63, and soon Edge (they're implementing Web Components now).

- Polymer 3 elements are available on npm, and can have npm dependencies. Bower is deprecated and has very few packages compared to npm.

- Polymer 3 elements are importable into other JavaScript modules. There was no way to import Polymer 2 elements into JavaScript.

These are huge advantages.

Not saying that is bad but it came to the price of a IMHO high price: the paradigm change of turning a Web Component into a JS module instead of being a custom element with behavior. I very much liked the idea of custom elements just being

user-defined HTML elements. Now they have a different face on - that of a JS module. Polymer 2 feels so much more 'natural' being a container for CSS, HTML template + JS. Now we have to live with ugly template literals instead of descriptive markup. I know that this train is gone by the deprecation of HTML imports but nevertheless i consider this the wrong decision. Having participated in W3C standards i know that specs not always necessarily represent the wisest decisions.

 

but we have to spent x days to migrate to the latest? Why just change if apps do well?

Furthermore we'll likely never migrate to Polymer3 which is a major step backwards in our opinion (lack of descriptive templates). We love webcomponents and Polymer 2 but the latest directions the spec went are a clear mistake - efficiency over architecture. It's a pitty that specs not always evolve in the right direction.

The specs didn't change between Polymer 2 and 3. Yes, we stopped using HTML Imports, but HTML Imports were already not going to be implemented by other browsers. We simply stopped requiring a polyfill indefinitely.

 

Sorry - but you hit that button in me again. It's pure frustration - i'm still hoping for HTML modules but certainly will never go with literal templates. That's simply rubbish

Polymer 3 and Polymer 2 component implementations are essentially identical, we just have HTML-in-JS rather than JS-in-HTML. All the lines of code are basically the same. The change in container format doesn't fundamentally change the code you have to write, or the operations Polymer has to do to instantiate elements and render templates. It's really all the same code.

That's what i'm talking about - if you just see it as 'we *just* have HTML-in-JS(...)' you'll hardly get my point or simply have different priorities.

 

Sorry for your frustrations. We are trying to make Polymer simpler to use by aligning with current standards and tools. We can't be an island forever.

I appreciate your answer and largely i agree. However my hope is on HTML modules should they hopefully see the light of day soon. Otherwise one of the major selling points for us is gone. It's a pitty that descriptive formats are so much underrated. Certainly some tooling could also help but we'll hardly start editing template literals.

Not that i'm misunderstood. Web Components are a phantastic technology - i guess it's the first time a reasonable complex model for components has been found that has a chance for real broad adoption. I even wish it would be promoted much stronger as in comparison to some JS frameworks it's still rather underrated. Polymer has done a great job allowing early adoption and providing the tools for a great experience. Love it and wish it may leave all those frameworks in the dust one day ;)

cheers Joern