Documenting CSS

Just like all other programming the CSS needs documentation. I’m afraid I’m rather bad at it: the times I’m lucky I’ve been able to document by simply talking to the developer taking over, and the unlucky times I’ve left no documentation at all. Talking directly is of course superior to everything else, you don’t waste time explaining things that are obvious (differs from person to person), but you don’t always have that luxury. So what I thought I’d do is list things I think are important to document, for the times when you won’t be available for answering questions.

Don’t be fooled to think all projects are alike. Sometimes you’re under tremendous stress just to get the basic CSS up and running; it isn’t reasonable to expect the same kind of documentation then… But most often you have an hour extra to just jot down a couple of lines about your interface.

  • How is the CSS file(s) structured? When you build large sites you often end up with over 1000 lines of CSS, and if you don’t structure them, you’ll end up with a mess. Even if you DO have a structure, it takes a lot of time to figure out someone else’s code. To give you some ideas of your own, I wrote about how I structure my CSS previously. You don’t have to use that one, just be conscious about your choice, and document it.
  • Where do I add new styles? Either it’s obvious from the previous structure or you need to make it obvious how to add new stuff. What if I’m adding a deviation from how a certain section looks, should I put it near that section’s styles, or near all other deviations? This question is especially important on sites with lots of campaign components with custom CSS. Trust me, your cleverly crafted structure will become a mess if you miss answering this question.
  • What can I do with existing styles? To make sure design ends up in the CSS and not in the HTML there needs to be some kind of overview of all available classes. Else people are going to hack things and try to duplicate your code. How do you handle columns, clearing, quotes, and floated images? Did you think of it yourself or do I have to add my own code? A good way might be to make a document where you tie the different classes to how they look when used.
  • How are different browsers handled? Struggling through browser hacks is a real pain in the ass, unless those hacks are properly documented. What browsers do you try to support, and which of them have you tested in? Did you plan for the future?
  • (Optional) Web standard basics. Working with web standards is rather different than working the old (table based) way . So if you know that oldschool developers will work with your code (are you sure they won’t?), it could be a good idea to shortly summarize the modern web mindset. I recommend using a lot of links here, not to waste time; people are very different in what they know.

If you’ve answered the questions able you’ve come a long way. Your code is understandable, and will stay in shape for much longer. Not to mention when you’re looking at some code in a year, thinking: “Who wrote this shit?! It’s a mess!”, and then figure out it was you.

Now, is there anything essential I’m missing, that you want to add?

7 responses to “Documenting CSS

  1. Great list! I have been n a similar situation about documenting JavaScript. This list can be applied to that one too.
    Another thing worth menioning is CSStidy, which can clean up and sort CSS when development is done. It can be a toll to keep CSS consistent.

    (fyi: I read this article and wrote this comment on lynx, since I doing som server confs at the moment. Works just fine.)

  2. Good write-up. This is really important when leaving your precious style file to another developer. Just the “Where do I add my own stuff” is good. A good thing if you don´t use your own “framework” that you can reuse in every project is to have a look at other frameworks like Blueprint. There are some nice stuff that you can be inspired of like structure and documentation. I would also recommend to have a look at minify. It combines, minifies, removes comments etc with multiple css files. The good thing is that you can work a lot with comments within the file, minify then removes this on the fly and makes a cached copy of the file. It also have a bunch of other great stuff in it.

    Here’s an example of my css and the minified copy

  3. I always structure my CSS like I structure all my code; modular.

    Each module gets its own CSS-file. Any selector in a module-CSS must start with that module’s ID-name (every module has a div with an ID of the same name as the module (div#recent-comments for example)).

    Module-files should _never_ style generic classes or elements. Everything should go through the #module-id.

    This way modules cannot mess with other modules and you know that if there’s a layout-issue with the “Recent comments”-module you look in the recent-comments.css-file.

    Generic styling and reseting/styling of basic elements is all done in general.css.

    Sometimes I have a site.css which styles the header, navigation, content, sub-content and footer-modules in one file. It’s sometimes easier to get an overview of the design if they’re all in the same file.

    I’ve also written my own constant-parser that removes the need for CSS-classes, and I save nifty constants in constants.css (or, if it gets massive I start dividing that up as well depending on what type of constant it is (list-styles, table-styles, div-styles, icons).

    After working on 150+ modules-sites for 2 years this is easily the most straight-forward, easy-to-grasp way of structuring your CSS and it leaves you with very few bugs.

    How annoying isn’t it when you fix a bug in one module only to introduce a new one in another? Structuring your code like this will eliminate problems like that.

  4. @Andreas, I work like that too, except I mark up every modules (or service, as it is called in our current project) with classes instead.
    The CM lets the subscriber publish multiple instances of each service on a page, and this makes it impossible to mark services with unique IDs. :(

  5. Ah yes, in some cases I use a class rather than an ID as well if the module (or service (that’s a new one to me, everybody here (Y!) says “modules”)) will be included more than once.

    In some cases tho, like an article-listing I’d consider the article-listing to be the module, not the article(s), so i’ll have a div#article-listing wrapped around all the articles, and each article gets a div#article-1234 as well, rather than just a row of div.article:s.

    I try to steer clear of classes as much as possible. I don’t know why really but I rarely see them used in a way that’s actually relevant to the HTML.

    In most cases classes represent too much design/behavior (.box, .left etc) for me to feel comfortable using them.

    The div[id] around the module adds to the structure of the HTML and is not there for styling but only for consistency and structure.

    Fact is my framework automatically adds wrapper divs around modules, this is great when you’re updating a module using ajax and you want to fetch it without the wrapper-div because you’re actually putting the response in the wrapper-div and should it contain a wrapper-div you’ll end up with nested divs with the same IDs.

    Obviously it all depends on how you use classes, but to me IDs make more sense to wrap modules.

    Think I just increased Friendlybit’s height by another 400px with this comment :). Perhaps a little wider comment-area in the coming design?

Comments are closed.