search

Polymer / old-docs-site

Old Polymer site. Replaced by these repos: polymer-project.org, polymer-library-docs
https://www.polymer-project.org
1.02k stars 2.44k forks source link

Docs for junior developers #1822

Open larsgk opened 7 years ago

larsgk commented 7 years ago

(Enhancement, Guidelines, Examples)

Background: I am currently helping a dev team from legacy ActiveX/Flash to a modern web solution. We are playing with Angular, React and Polymer (1 now - probably 2 soon), and I am aiming for WebComponents as it's going to be a long lived solution) and I've noticed that the Polymer docs seem to be targeting slightly more advanced developers than e.g. the angular docs.

NOTE: I know you don't want people to see Polymer as an app framework - and I am not asking for larger polished app-toolbox solutions - just guidelines and suggestions to 1) help people away from frustrating pitfalls and 2) not automatically push people to e.g. Angular that seems to have all batteries included. As WebComponents - and especially with Polymer's icing on the cake - make it possible to do 80% of what major app frameworks do, you must expect that most will not consider adding a big and bloated framework but just add their own extra glue to a clean WebComponents/Polymer based solution => in practice, it does become the app framework (which is totally fine).

Some concrete examples that I would suggest you should consider:

  1. Create a section with the most relevant well known standard software design patterns and how they work or could be done in WebComponents/Polymer land, so at least people don't go too much frustrated in the wrong direction

E.g. I recently had to spend quite a bit of time figuring out how the inner workings of polymer's behaviors and binding works to make a singleton that actually behaves as a singleton with bindings - and not like the many examples of it done wrong in Polymer out there on the intertubes. My somewhat hackish solution is here: https://beta.webcomponents.org/element/larsgk/gamepad-service (hybrid solution with singleton/static parts). Another (earlier) attempt here: https://gist.github.com/larsgk/28d4609f1a9eb1f8f2284962acfa9052

  1. a better explanation of what goes on under the hood when doing e.g. bindings (exact events fired, etc..)

  2. guidelines for wrapping 3rd party stuff in global and local scopes (helping porting to shadow dom/components paradigm, etc.)

  3. examples of proper integration with well known app frameworks, utils, transpilers, etc.

There is SO much mis-information on this out there and add to that all the stackoverflow, etc. describing how to do this properly in Polymer 0.5 ... not helping any junior making the right implementation.

/cc @notwaldorf @robdodson

ghost commented 7 years ago

Thanks for this. I am creating some new Getting Started stuff for Polymer 2.0 and will use your feedback while doing so.