CSS is complicated.
Understanding how CSS works is the first hurdle, but even after you understand the box model and other complexities you still won't necessarily understand how to organize your CSS code. It seems like with most projects nothing turns to spaghetti code quite as fast as the CSS files.
Kyle Neath, Director of Design at GitHub, wants to make working with stylesheets a bit easier and he believes that the way to do that is for teams to create better documentation. That should be no surprise given GitHub's obsession with documentation, but Neath has gone a step further than just telling you you should document your styles, he's actually created a way to do it – Knyle Style Sheets.
The idea is to write documentation within your styles that can then be process into what Neath calls "a living styleguide." It works a bit like Docstring processors for Python or Neath's inspiration, TomDoc. Here's how Neath describes his stylesheets:
If you're curious, head over to GitHub and look over the KSS documentation.
Rails fans can also check out developer Garrett Bjerkhoel's KSS Rails which provides a Rails 3 engine you can add to your existing application to automatically parse any CSS files found in app/assets/stylesheets.
It won't solve all the hassles of working with large and complex stylesheets, but documentation can help tame some of the problems with CSS by ensuring that everyone is on the same page. Never underestimate the power of good documentation.
