Better inline documentation about oocss HOT 17 OPEN

I think this is a goo idea.
Especially documenting the css-hacks etc to make it clear why things are done this way.

from oocss.

I like the idea of using better comments, we need an easy way to build compressed versions of the files (maybe tools from Yahoo! or Google?). Unfortunately, lots of people will use the files directly however we provide them. We'll need to compress, remove comments, maybe even combine them.

from oocss.

It's a learning process. People should understand why it's better to use minified copies than the original code (Also it should be explained in the docs).
An idea i had some time is to have one master file that @imports all needed stylesheets but this is another discussion. I'll create a ticket about this soon.

from oocss.

@imports aren't great for performance because there are still lots of http requests. Ideally a site should only have one css file in production. (The only exception is the very most complicated websites)

from oocss.

Hehe. I knew that some people will get this wrong. :)
My plan was not to use this master file in production.
My plan was to use a master file for development for easy integration of oocss files.
Doing so you dont need to mess in your .
I dont see a reason to not do it the way i suggested.

Before deployment the @imports in this file should be replaced by the content of these files.
Then minifying etc. pp.

from oocss.

as the yahoo-people reccomended:
allways use a build tool :)

concat files -> sprite file -> minify file

I prefer gnu make

from oocss.

I have an idea, what if we do a build step in the project. Like YUI we can have a dev version and a minified version. That will allow more flexibility in comments, etc. Then, each time we have a new version, we auto-run the build tool to create the minified version. Would that work?

from oocss.

Yep, thats actually the best way i think.

I think creating a branch 'minified' where the compressed files live would work well.

This way we dont need to mess with the directory structure and can switch even on production environments quickly between minified and regular.

That allows easier debugging & performance if needed.

I dont know how to do it technically but that probably isn't a big deal.
(pre commit hooks or so)

from oocss.

I just noticed that this wouldnt solve the whole problem since there would be many different files, which would result in many requests. Any ideas how to improve that?

from oocss.

My two cents: use Natural Docs [1] for the documentation and Combiner [2] to combine CSS files before minification. I am using these tools as part of a build process based on Apache Ant, for Javascript files, and they should work equally well with CSS files.

[1] Natural Docs
http://www.naturaldocs.org/

[2] Introducing Combiner, a JavaScript/CSS concatenation tool, by Nicholas Zakas
http://www.nczonline.net/blog/2009/09/22/introducing-combiner-a-javascriptcss-concatenation-tool/

from oocss.

Follow-up: using Natural Docs to generate HTML documentation for CSS requires some extra configuration.

You need to declare the language and associate it with CSS extension. This is done by inserting the following lines in the file Language.txt of Natural Docs Config folder:

Language: CSS

  Extension: css
  Block Comment: /* */

from oocss.

I would like to voice my view that development code should be readable and formatted.

Production code should be minified, etc, but that should be "up to the reader", as they say. And yes, many will just use these files as they are, but that is a lesson they need to learn.

When I have spent a bit of time this afternoon re-formatting the new code I pulled down today, just so I could read and understand it. This completely screws me when I try to merge any future changes. I can't merge. I have to toss what I have and re-format again.

My 2 cents: let those who wish to use the "full text" use them, please don't streamline this code for them. I think streamlining makes it harder for those of us trying to learn the code.

Thanks

from oocss.

I think Natural Docs would be a bad choice since it's mainly built to document functions etc. – Things you don't really have in CSS.

What I found recently is Docco.
The link explains it probably better than I would.

from oocss.

@mklappstuhl, despite having recommended Natural Docs, which seemed a good choice at the time based on its language-neutral stance, I have to admit after 8+ more months of use on both JavaScript and CSS inline documentation that the tool is not ideal. There are actually deeply rooted assumptions about programming languages, like expecting that functions will be documented with comments before each function, that have to be turned around. Also, the keywords provided by default are not ideal for CSS: it is awkward to document CSS rules as "classes" when they target elements or pseudo-elements.

On the other hand, I have a hard time reading the side by side documentation generated by Docco. Literate programming should not prevent you from putting comments within the code. Also, literate programming tools a la Knuth should allow to order the comments independently from the code order.

Edit (December 28, 2010): it is actually possible to define new keywords or alter the behavior of keywords in Natural Docs.
Reference: http://www.naturaldocs.org/customizingtopics.html

from oocss.

@phpwalter - everyone has a different idea about the right way to format code. I format it the way I like to read it, which is one line per selector. There are editors (css edit, i think?) that will let you view it however you want and save it in a way that matches our style.

from oocss.

Why not just use SASS? Comments can be written in the .scss file and can optionally be removed when the css is compiled. Also, using .sass or .scss a file, one can choose to use the preshipped compiled version of OOCSS or create their own custom compiled version. This would allow for one line selector and properties. See http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#output_style for more info.

from oocss.

There are also online css re-formatters, I have one on my site:

http://seanja.com/tools/csstidy/

(Set the compression to low/normal to reformat the css for readability if you don't like the inline formatting)

from oocss.