Docs for 1.0

[David Meads]

To whom it may concern:

Hi, I am a developer tasked with creating a new application with Polymer 1.0. There are many things I really like about Polymer and I can see why our architects have chosen to use this platform. With that being said, I am struggling to find documentation that is specific to 1.0. 

The things I need to understand are sometimes found in the 1.0/docs/devguide and then sometimes the things I need to understand are in the migration guide. Many times I find myself reading docs for 0.5. Not because I want to develope a 0.5 site, simply because it is the only place I can find documentation on areas that I am attempting to learn. The problem with reading 0.5 docs is, I never know what parts are included in both versions of Polymer. 

The feeling I have had at times is that I should just write my app in 0.5 and then migrate since there is consistency in 0.5 documentation. Since I have never used Polymer and would like to go from 1.0 forward, I was hoping to not need to spend more time on 0.5. 

Mostly I would like there to be ONE reliable place where I can see 1.0 documentation that I know is correct to the version I am using as well as complete.  

Is there some advice you can give me in finding the correct and complete documentation for 1.0? 

Thank you very much for your help. With all this being said, I remain very excited and optimistic having Polymer as a part of future. 

Respectfully,

{

     “David Meads”: “Software Developer”,
     “iGlobal Stores”: “801.989.0000”
}

[Eric Bidelman]

Hi David, 

Sorry for the troubles. The place to go for 1.0 docs is https://www.polymer-project.org/1.0/docs/devguide/feature-overview.html.

It would help us greatly if you could share what you found missing from the 1.0 docs or where we can move things around. It's always good to get new user perspectives.

FWIW, we recently removed the 0.5 documentation from Google's index, so it should no longer turn up in searches very shortly. It'll still exist on the website if you need to drill into it.

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/CACGKS-Po2Csn8pe%3Dm%3DkoQxumyVmVAN00oHcrK0mdW7ndixfG_Q%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[Colin Cannon]

I couldn't find any documentation related to unit testing in 1.0.  All I found was this page: https://www.polymer-project.org/0.5/articles/unit-testing-elements.html and it says it is for 0.5.  

[rictic]

You're right, I don't see any documentation for testing in 1.0, that's something we can address. Fortunately, I don't believe anything testing-related has changed from 0.5 to today so that doc is still a good guide.

[David Meads]

Thank you all for you prompt replies. I have told my team to document the problems they have found with the docs and I will be sure to pass those findings back to you. 

Thanks again,

David

--

[andreas...@hotmail.de]

Hi Eric, to add my two cents to this: What I've found lacking are demos/examples of how to use mixins. For example, I've been trying to figure out how to style a paper-dropdown-menu with the available mixins and the recommendation of using the -paper-input-container-color to stlye stuff. I haven't found a single example in the docs how to style something like this (how to nest those two to make it work?). Still haven't figured it out :/

[Eric Bidelman]

Here are the docs on mixins:
https://www.polymer-project.org/1.0/docs/devguide/styling.html#custom-css-mixins

On Mon, Sep 7, 2015, 4:09 AM  <andreas...@hotmail.de> wrote:

Hi Eric, to add my two cents to this: What I've found lacking are demos/examples of how to use mixins. For example, I've been trying to figure out how to style a paper-dropdown-menu with the available mixins and the recommendation of using the -paper-input-container-color to stlye stuff. I haven't found a single example in the docs how to style something like this (how to nest those two to make it work?). Still haven't figured it out :/

To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/16d40b51-9a3a-44f0-ae5e-995032f4e8cd%40googlegroups.com.

[andreas...@hotmail.de]

I've seen those docs but somehow I just couldn't get it to work yet (that's why I was hoping for a specific example in one of the element's catalog docs. Anyway, I'm looking at the docs again and will give this another shot tonight ...

[andreas...@hotmail.de]

I've been making some progress here. I think I'll be able to figure it out. Somehow looking at the actual component's code made more sense to me and makes it easier to understand how mixins and custom properties work than looking at the docs. 

By the way Eric, maybe you can check this thread out and recommend to me how I can help out with improving the paper-elements?

https://groups.google.com/forum/#!topic/polymer-dev/SOwdL1BSDR0

[Eric Bidelman]

If you have suggestions about element doc improvements, feel free to file bugs/feature requests on the individual elements or submit PRs that update the doc sections. Requests for the element catalog can go here: https://github.com/Polymer/polymer-element-catalog/issues

To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/61711d55-e86a-43db-9797-146bf2bde8df%40googlegroups.com.

[Arthur Evans]

One thing I will add is that because custom CSS properties and mixins are so new, I'm not sure we've discovered the best practices for documenting them. Also, in many cases we're still working out the right set of mixins & properties necessary to style a given element. It's not uncommon to find a reasonable use case that the author didn't anticipate.

If you find something you can't figure out how to style from the docs, please file an issue against the element's repo. There are a couple of possibilities:

1) The developer didn't think to expose that property.  Possible code fix?

2) You can style it using a mixin, but it's not obvious where to put it. Possible documentation fix?

3) There's some good reason the property isn't exposed on this element, which may not be obvious (and should perhaps be documented). 

In any of these cases, opening a github issue is a good start. (If you're just not sure how to do something, Stack Overflow is a good start).

-Arthur

To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/CACGqRCBvaUFNHv2WRFrPThkgmOTrTMrcEMONMCpbmZOAy68SSQ%40mail.gmail.com.