Skip to content

Conversation

@Wattenberger
Copy link
Contributor

I took a stab at making the props in the docs easier to parse - I like when the attributes are very visible, but totally understand if the style is too bold.

image

Since props in the docs are just generic headers (h3, h4, h5), I targeted h4 and h5s to prevent changing headers in other parts of the docs. There are a few prop declarations that use h3s, which are updated in the second commit 🙌

@CLAassistant
Copy link

CLAassistant commented Oct 7, 2018

CLA assistant check
All committers have signed the CLA.

Copy link
Contributor

@mcnuttandrew mcnuttandrew left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wow! Thanks for doing this, this is great. This is a good win for consistency across the docs. I pulled down your PR and applied a few tweeks. I think using blue for a stronger highlighting is a good move, but I think it's a little distracting for prop so i moved it to be as the code blocks and made the prop titles bigger and underlined. What do you think?

screen shot 2018-10-07 at 9 13 04 pm

I think it is good to break up the lines of the prop description so that it is a little easier to see. I know this is a kinda big/tedious ask, but as long as you are doing such good legibility upgrade would you mind inserting line breaks before and after all the type declaration, eg

#### data
Type: `Array<Object>`
Array of data for the series.

will become

#### data

Type: `Array<Object>`

Array of data for the series.

Which is important i guess for how our markdown interpreter interprets the markdown?

I'm really glad you are taking a look at this, making docs easier to read is real important. I ran a lighthouse accessibility audit over the docs page and we don't really do very well. This PR pushes us in a good direction on that front.

@Wattenberger
Copy link
Contributor Author

Ah yes, good call! Updated to the underline and moved the blue highlight to code elements following a h4/h5. This also includes inline code elements in the text - I could go either way on the blue highlight in general. I think it's a little loud, but not necessarily too much, plus it gives the docs a bit of personality which I like.

image

I went through and added new lines around Type: and Default: statements - I think things are looking great!

@mcnuttandrew
Copy link
Contributor

This rules! You are big a hero for doing all this. I'll merge it in now, and I'll try to cut a new copy of the docs this evening.

@mcnuttandrew mcnuttandrew merged commit 3558e50 into uber:master Oct 8, 2018
ayarcohaila pushed a commit to ayarcohaila/react-vis that referenced this pull request Jun 30, 2021
* Make props in documentation easier to parse (uber#984)

* docs - make header usage more consistent (h4/h5 for props) [uber#984]

* update doc props styles - change blue highlight to underline

and highlight code instead

* docs - make sure Type and Default declarations are individual paragraphs
ayarcohaila added a commit to ayarcohaila/react-vis that referenced this pull request May 30, 2023
* Make props in documentation easier to parse (uber#984)

* docs - make header usage more consistent (h4/h5 for props) [uber#984]

* update doc props styles - change blue highlight to underline

and highlight code instead

* docs - make sure Type and Default declarations are individual paragraphs
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants