The official book of California Stylesheets
(and that's okay)
It's a book about writing CSS.
And not writing CSS.
The official book of California Stylesheets
(and that's okay)
It's a book about writing CSS.
And not writing CSS.
Knowing is half the battle. The other person knowing is the other half.
You can know your system inside and out but you can't know what they'll know. You don’t even know who “they” might be. It might be you. But you might have amnesia! If your life is a soap opera. Or if you code all the time.
Using a system that people can read, even if they can't write it, is crucial. The conventions and library used might not be available to the person on the other side. Or that person just might not look them up. Your classes and conventions need to make sense on their own, within a vacuum, as much as they can.
Document your code first for yourself, to assist you while you are writing it. Then, put in things that will make it make sense to your team. Then, or maybe even do this part later, make it make sense to anyone who might ever read it.
This might seem to clash with the “write the least amount of code that works” advice from earlier. It does. All documentation is a hedge against screwing that up.
Writing documentation follows all the rules of normal writing. The first is that you should always write for your audience. That’s those three groups of people: You, your team, and everyone else.
My audience is slightly self-loathing web developers who want to cut corners on the part of the stack closest to the user, the only human element in this whole web development equation.
Are they dead inside?
No, that's me.
They’re doing just fine, especially with all this time they’re saving not writing CSS. That's another important rule: Don't project your own problems onto your audience. (I’m working on it.)
Comments in your code are not the place to vent about how bloated the build process has gotten. Save the passive-aggressive communication for the platform purpose-built for it: Twitter.
All of this audience stuff applies to writing anything, including code. Match the style and tone of what’s already there, written by the team, because that’s what they’ll understand. Your latest feature may be a masterpiece of functional programming, or use the hottest new microframework, but unless the rest of the project is written that way, it will always be out of place and getting in the way of progress.
Unless everyone comes around on using that microframework. It does happen.
Concept documents are an overlooked form of documentation. The concept doc is an early-in-the-project form of documentation aimed at getting everyone on the same page conceptually. It defines terms and explains ideas in an effort to boil off early miscommunications.
We work in an industry full of people who suck at naming things (See the previous chapter “You suck at naming things”) so for almost every word we use there are five different definitions, and five more common misuses.
Try asking people in tech to define words right after they use them. You will be shocked and amazed at what you hear. It will also make you very unpopular very fast. Maybe don’t do it during meetings.
You can have a template, a partial, an include, a block, a snippet, an import or an append. Do they all mean the same thing? Only if someone on the team realizes it. Sometimes they’ll mean slightly different things to everyone on the team. A concept doc helps clear it up before the miscommunications cost time and energy.
It’s also the bane of existence for the people who cannot define the words they just used. See, these people are concept ghosts. They exist entirely in the nebulous space created by the endless miscommunications, stretched definitions and not-specific-enough specs. All of it serves as a smokescreen for them, a plausible deniability exit on their highway of lifetime laziness.
They’re bullshitters basically. A concept doc gives them way less wiggle room.
Concept docs shouldn’t be longer than a couple pages. They should include definitions, explanations of core concepts (If you’re building an interest rate calculator, explain interest rate here), and a section on perspective. That’s just a bunch of relevant numbers, like market size, campaign size, audience size, anything that gives your team a sense of perspective and stakes.
When projects get big enough, they should have their own external documentation, separate from the codebase. Doing this right from the start is usually a drag for everyone involved. Greenfield projects are fun because they don’t have things like external documentation. Enjoy this period for as long as you can.
The one exception here is APIs. APIs should have external docs right off the bat. Yes, it’s a pain to get them into a web format. But it’s more of a pain for the rest of the team to go diving through the codebase that drives the API. There are almost always automated tools for this.
The other exception, if the team/project is big enough, is a visual style guide: Something that documents in very general terms (while also giving a ton of specifics) what the project should look like. Document your standards here early; have less design arguments (“conversations”) later.
Since it’s typography-focused, CASS is great for documentation. It lets you keep the markup simple. It also lets you quickly give your docs a look, even if they’re auto-generated by something other than you. Visual style guides are easy to put together because all of the brand color standards can be CASS colors right up until you overwrite them with your own.
The Gumroad version contains a secret chapter that spills the dirt on CSS preprocessors, a tech CASS no longer uses.
