search

vega / vega-lite

A concise grammar of interactive graphics, built on Vega.
https://vega.github.io/vega-lite/
BSD 3-Clause "New" or "Revised" License
4.68k stars 611 forks source link

Overhaul Docs #1226

Closed willium closed 7 years ago

willium commented 8 years ago

Our docs css and markup has become riddled with tack-on solutions to individual problems. Now that we know what it looks like, and know how we want to extend it, I think it's worth rewriting following some guidelines.

I think these changes can be accomplished without losing any simplicity while making significant gains in manageability, debugging, and growth.

I suggest:

kanitw commented 8 years ago

I like SASS especially if we don't need to complicate our build system too much.

BEM seems to have some merit, but I'm not convinced yet. To be fair, I'm not that familiar with it but I doubt if it is worth to force everyone in our team to spend our limited time to learn new concept while the gain is relatively small. (If you wanna enforce BEM on the team, everyone has to learn it.)

We should keep in mind that we're a small team with limited resource. Fixing bugs and introduce useful features should be much higher priority than (over-)optimizing the docs code because unlike when you do a web-app, our docs probably wouldn't grow that much in terms of functionality.

That said, migrating to SCSS should be not so time-consuming so please go ahead if you wanna do it.

@domoritz thoughts?

kanitw commented 8 years ago

Also, there is also a decision to be made to pick between all these CSS convention http://clubmate.fi/oocss-acss-bem-smacss-what-are-they-what-should-i-use/

I assume you have done some research and think BEM is the superior one?

willium commented 8 years ago

We can discuss Monday!

willium commented 8 years ago

Going to table this for now since it's vague and change the label to in-queue

kanitw commented 8 years ago

I wouldn't mind if we just close it because we don't really need to do anything described here.

kanitw commented 7 years ago

I don't think we will ever do this in the near future. I'll close.