How to document CSS for a large site [closed] - html

Question

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
We maintain a fairly large site with a lot pages. As the pages grew, so did the HTML and CSS. Is there any good way to document these? Like which page uses a particular selector, etc. What's the best practice for maintaining CSS for a large site?

Answer 1

In my experience, CSS is not maintainable. If CSS were a room in your house, it's the basement...it collects things over the years and after a while you tend to have more stuff in it that is of no use vs. stuff you want to keep.
As such, I recommend starting fresh every few years.
Barring that, some suggestions:
Maintain the CSS dev-side in as many separate files as it makes sense to have. Use a minimizer to compress and combine it all into one file for deployment.
look into OOCSS (Object Oriented CSS) methods. I try to use that these days for sites that have large teams of developers. The basic concept is to have more class names in your HTML, but what class names you have are much more re-usable across the entire site, so your CSS files should remain more streamlined.
build component libraries. A major goal is to NOT have specific css for each individual page. Instead, leverage reusable code and design patterns across the site.

Answer 2

We use rails and follow this architecture: http://codefastdieyoung.com/2011/03/css-js-organization-best-practice/
Depending on the framework you use, you might have to tweak the logic accordingly.
Brief explanation of the architecture:
In rails there is a way to specify a common ID for a group of pages.
For ex: all the pages related to users management can have this id: body#users-registration.
Similarly all the pages related to reporting services ca have this id: body#reporting-services
Having said that, have a common.css file which contains generic styles that are reusable across the site - like layout styles, li, p, panels, etc.
And then have separate css files for each & every group of pages: users-registration.css, reporting-services.css. These files will have the styles that are specific to the corresponding group.
In this way we have managed to avoid conflicts across the pages as well.
Note that we finally combine all the CSS files into a single css file and render that in production.

Answer 3

I've found that commenting my CSS and targeting HTML tags vs "class1, myselector27, etc" has made for a lot less code, and simpler to read later on. If I have a JavaScript event that needs to be isolated, I wrap that component in an id and comment the base CSS file accordingly.
reset.css
fonts.css
main.css
main.css
/*
** Image Slider for products.php
*/
#slider_products {...}
#slider_products #slide_container {...}
#slider_products h1, p {...}
#slider_products img {...}
If you are using an IDE (like NetBeans) these comments can be made visible (and you can also write as much descriptive text as necessary, if need be)
I've maintained CSS files for sites with over 200 pages of content, and those with 20 pages. In either case, my CSS files have never been in the 1200-lines-of-code-range, which I've seen in a friend's portfolio site (no names :-)), but his site is #best 20-30 pages - ALL of which share the same design, style, look - it's OVERKILL. One has to believe that if the CSS and code were to be combed-through those 1200 lines could be reduced substantially pretty quick.

Answer 4

There are a few things you can do.
Place your the CSS in your stylesheet in order of the page. So, header styles at the top, then main content styles, then footer styles. Below that, you can add additional styles for certain uses.
Use comments in your styles, e.g. /* ### Styles for Links in Main Content #### */
Use separate stylesheets for separate sections, if the CSS is large enough. So, if you have a section of the site that deals with a specific topic and it has significant style modifications, give it its own stylesheet and only reference it in that section.
Use the cascade wisely and cut down on the amount of css you write. A simple example here: http://csswizardry.com/toybox/use-the-cascade/

Answer 5

I've seen a few systems that delineate between CSS written for the interface, with reusable class names as DA points out, but they did go ahead and give an architectural breakdown of these classes, since their intention is to be reusable. Then they went on to use verbose selector names for components and granular features - which generally weren't documented, and were provided by 3rd parties mainly.
It worked fairly well, and I imagine if the interface were redesigned at some point it would be an arduous but doable job to re-work the interface CSS and documentation, while leaving the component styling down to the 3rd-party providers/developers, or whoever creates the components.
As the others have said, don't let CSS documentation lure you into avoiding minification, even if it isn't automated, but beware, if your CSS is sprawling and unaccountable when you minify, you may find your resulting styles aren't quite on par - depending on the minify settings used.
EDIT:
Hot off the Google+ feed - Jonathan Snook is writing up something related to this thread, here's the temporary link to keep an eye on: http://smacss.com/