Seeking feedback on new elm-css docs

[Richard Feldman]

Hi all!

I'm working on a major revamp of elm-css and I'm looking for feedback on the new docs, especially from people who have never used elm-css before.

To view the new docs:

1. Check out this branch
2. Run the docs preview on it

In particular I'd like to know what questions you still have that the docs didn't answer.

Thanks!

-Richard

[Brian Hicks]

Big things:

- Html.Styled.Attributes: styled is a really complex type with no documentation. I think I see what it's doing? It's not completely clear. (my best guess: this lifts a plain html-producing function to a styled html-producing function?) But why?

- It's not clear why you need Html.Styled.{Events,Keyed,Lazy} from the docs. I assume this is because you're defining a wrapper type over regular Html?

Little things:

- Html.Styled: "This file is organized roughly in order of popularity" is followed by node, which we maybe shouldn't use so very often.

- Html.Styled: the docs for span mention adding class. This shouldn't be needed in this case, should it?

- Css: the H4s don't read as headers. I thought you didn't have headers at first! But the explanation is clear enough once I figured it out. Maybe use H3s instead?

- Css: "you'll get a build-time validation error (RGB values must be between 0 and 255) if you try to compile it to a stylesheet." Isn't this a runtime error now?

- Css: broken link to #border2

Overall:

I'm super excited to use this to make my styles go faster! This should do the right thing with eventual SSR stuff, right?

--
You received this message because you are subscribed to the Google Groups "elm-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elm-dev+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elm-dev/59353896-3627-47fe-acb3-a09466c983a6%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Sebastian Porto]

Hi

I have been using 12 for a week, I really like Html.Styled. 

Here is my feedback about the docs

• There are lots of references to stylesheet in Css.Foreign, which is deprecated, please remove, this is confusing

• Css.Foreign stills shows union types for classes, which I understand is deprecated

• I find Html.Styled.Attributes.styled a bit odd, I guess is useful but why whould you use this over css?
  

• Should there be Html.program and programWithFlags?

• In http://package.elm-lang.org/packages/rtfeldman/elm-css/latest/Css batch is not clear what is for, there a are couple of uses e.g. paragraphFont, but that is not used anywhere

• Please to show how to target descendants class

• Is not clear how to migrate from 11 to 12, specially if you were using stylesheet, would be nice to have a small migration guide
  

Sebastian

[Richard Feldman]

Wow, thank you for the detailed feedback! This is really helpful. ❤️

I'll take a pass at revising the docs for the next release.