Monthly Archives: March 2012

We Suck at Apologies


Several incidents in the past few weeks, both public and private, have led me to the conclusion that we all suck at apologies when we have offended people. I’d like to try and start a conversation to see if we can fix that.  I feel like I am qualified to give advice here, as I spent my 20’s as an angry and often offensive guy, who had to apologize quite a bit.  Because of this, I’ve learned a little of what works and what doesn’t.

Let’s start with a premise.  You said something that offended someone somewhere. They are angry, and they have called you out on it in some fashion.  (It’s vague, but every example I could come up with might have been offensive.)

“Why should I apologize, what I said (or did) was right?”

This here is the major problem we have with apologizing. We think that apologizing means that we are saying “I was wrong, and you were right.” It doesn’t.  When you offend someone, you have damaged your relationship with them. Whether you are an individual offending another individual or a company who offended a potential market, your actions have damaged the relationship.  The true purpose of an apology is to try and fix the damage in the relationship between you and the offended party. That should be your goal.

“I didn’t mean to offend you.”

Actions have consequences, intentions do not matter.  Actually, it would be better to say, intentions can mitigate consequences, but they cannot erase them.  Suppose I hit a young man with my car. That my intention was to drive home has no impact on the consequence that the young man’s leg is broken. Now the fact that I was soberly driving home, and did my best to swerve out of the way can maybe mitigate what the law says about my culpability, but it cannot fix the man’s leg.

So, good on ya, that you didn’t want to offend anyone. Unless you’re a deliberate provocateur I don’t assume anyone believes you did.  If you were deliberately offending people, I assume you don’t have any interest in apologizing.  So if you are apologizing, shut up about your intentions. You just sound like you are trying to excuse yourself.

“I don’t see what you are getting so upset about.”

This is a shitty, defensive way of saying “I don’t understand how I offended you.” That’s fine.  It is perfectly acceptable to not understand how you have been offensive. If you were able to wrap your mind perfectly around the thoughts and considerations of the offended party, you probably wouldn’t have taken the action that offended them. It’s perfectly fine to ask for clarification and an explanation. Just try not to phrase that request like an asshole.

  • “I’m having trouble wrapping my mind around this, can you explain where you’re coming from?” Good.
  • “Can you tell me why a person like you is offended by this?” – Bad.

“I can’t have said something homophobic, I have quite a few gay friends.”

Repeat after me: There is no such thing as a “ghetto pass.” That you have gay/female/minority friends does not mean you can’t say homophobic/sexist/racist things.  It means that you probably shouldn’t say them, and perhaps you should check to see if you still have those friends.

“You’re overly sensitive.”

This encapsulates a lot of things but at the core of it you are denying the reasonableness of the person taking offense.  The thought here being there are thoughts that while controversial, reasonable people can talk about without taking offense.  There are two problems with this.

The first problem with the reasonableness trope is that it assumes offense is an intellectual response.  It’s not, it’s an emotional response. Therefore reasonableness of the offense is irrelevant as offense in this case is not a product of the reason.  You can tell someone to stop being sad because their life is overall great, but if a personal tragedy has occurred, you can’t stop them from being sad. Likewise whether or not it is reasonable to be offended is irrelevant in the face of actual offense.

The second problem with reasonableness is that it doesn’t matter. Because reasonableness is part of the right/wrong discussion. “It is not reasonable to be offended over this, therefore you are wrong and I am right.”  –which is irrelevant, because apologies aren’t about right and wrong, they’re are about repairing the damage to the relationship.

“140 characters/email/IM is not enough to have a proper conversation about this.”

You’re right. Happy?  Now stop wasting time and move to a higher bandwidth form of communication.

“That’s not what I meant.”

Okay, this is a tough one, and it’s different from “I didn’t mean to be offensive.”  It happens when what they think you said and what you think you said are two different things.  It could be because of someone mishearing you. It’s also perfectly possible that someone is reading into what you have said or done, and giving it a context that makes it offensive to them. It’s also possible that you were not communicating well.

Again it’s time to remember what’s important, fixing the damage.  So apologize first, get acceptance that you want to fix the damage, then start to talk about the misunderstanding.  Ask what language you could have use to make your intended meaning come through.

So how should you apologize?

  1. Start with “I am sorry I offended you.” No qualifiers.  No “If I offended anyone.” You’re sorry that the relationship is damaged and that you caused the damage.  Start from there.
  2. Seek an understanding of what you did that caused offense, and acknowledge it.
  3. No excuses. Unless you were kidnapped, drugged and slammed down in front of a keyboard or phone, you are responsible for whatever you did to offend someone.  Even if it is a “not what I meant” incident. You’re responsible at least in part for the misunderstanding.
  4. Don’t apologize angry. When we are criticized, it’s easy to get angry and emotional ourselves, and therefore get in the way of a real apology.  If the criticism you receive makes you angry or defensive, then wait and calm down.  Very little relationship damage can be fixed with anger.

There you have it, apology advice from someone who’s had to do a lot of it. It’s not about winning an argument, it’s about saving a relationship.

CSS Variables Draft

Thanks to Molly Holzschlag’s tweet yesterday, I learned there was an Editor’s Draft of CSS Variables.

Let me first say that I think it’s awesome that the W3C is taking this on. I think that variables in CSS will ultimately be a good thing.  It will make it easy to reuse colors and other CSS properties.  It will make large amounts of redundancy go away.  It will make CSS files smaller, and therefore give less toe-holds to bugs.

That being said I have a major complaint with the implementation–in a word “data.”

See, here is how CSS variables are supposed to work according to the draft.

I create a property in the root named “data-header-color.”

Then to refer to that color elsewhere, I use a construct that looks like a function named “data()” to retrieve it as so:

As far as I can tell, the only explanation in the draft for why this is, is that it is trying to match the HTML specification for “data”:

The naming here is loosely based on the form of custom data attributes in HTML5. However, as defined here, the syntax for variable usage is different from the syntax for variable definition (i.e. data-foo for definition, data(foo) for usage). Some have suggested that the syntaxes should should match, using functional syntax in both cases. Others have suggested using a prefixed symbol instead of functional syntax (e.g. $foo) for both the property and usage.

Well at least they are aware that some might object to this format.  So let me add my voice.  I object. Variables are a pretty standard construct, people know how they work. Make them work like variables in other languages.  I have a bunch of reasons here:

  • Two different syntaxes for creation and consumption seems confusing
  • It looks like you’re calling a function, but you’re not.  You’re referring to a variable.  That’s confusing.
  • CSS and HTML don’t have a lot of overlap in syntax, why is adding some a good thing?

My preference here is that I can just use plain old words as a variable, then consume them as plain old words. That being said I would be okay with a prefixed symbol, like a $ if it comes down to some sort of parsing issue.

That’s my major problem with the draft, but I have one other issue with the behavior on invalid variables. Like if you set the margin to #FFFFFF. Basically if you have this code:

Then the p comes out as red, but if you have this code:

The p comes out transparent.

This sort of change in behavior might be pretty confusing. The explanation makes some sense:

The invalid at computed-value time concept exists because variables can’t “fail early” like other syntax errors can, so by the time the user agent realizes a property value is invalid, it’s already thrown away the other cascaded values. I think “attr()” needs to rely on it as well, as its behavior is almost identical to variables.

But I imagine this is something that browser manufacturers can handle as they control the behavior of “throw[ing] away the other cascaded values.” They could hold on to cascaded values until they are done computing variables.  But maybe I’m missing something here. But it’s also worth considering if this will make invalid CSS easier to track down. I doubt it, but until a browser implements these, it will be hard to determine if that is true.

Anyway.  The good news here is that this is the editor’s draft, not the recommendation. This means that now is the time to start analyzing this spec and commenting on it. So what do you think?





Search, Hold the Server

Being a content site, it was pretty important that have search–which was pretty hard considering that I didn’t want to have any server-side components involved.

At first I thought I would just let Google index the site, and hook up a Google search box on the site to solve the problem. That was certainly an option.  I thought I would have to do some SEO magic to make it happen correctly, but it was doable. In fact, Ray had solved this problem already.

But then I got to thinking, wouldn’t be cooler to rise to the challenge of a search without a server? Why, yes, yes it would. I broke up my needs into two parts:

  • An index of the site’s content
  • A mechanism for searching the index and displaying the results.

I kicked around a few ideas, but finally settled on the idea of creating a JSON file that had an array of objects with title, url, summary, and condensed content info. If I had such a file, all I would have to do is search through the JSON to find results. So the second part of my search was a snap.  All I had to do was:

  • Pull down the JSON file
  • Run searches against that JSON file
  • Present the results

All of this was pretty easy to do, and not revolutionary.

The difficult part was making the index in the first place.  The added difficulty is that I wanted to use JavaScript for everything.  So I couldn’t just use a shell script or some other easy way of indexing the files. Basically I wanted to remove barriers to entry, so an OS X shell script would create an obstacle for Windows based HTML developers to get involved.

Trying to do this with JavaScript in a browser was very hard. While there is a File API for the browser, you can’t use it to point at arbitrary directories on the file system like the site itself, you can only really point it at a sandboxed space. This made indexing kinda impossible.

I said I had to use JavaScript; but I didn’t say I had to use a browser. Enter Rhino the Java interpreter for JavaScript. Rhino gave me the ability to call Java File IO classes from JavaScript.  This allowed for easy indexing of the content. Now this might be a bit of a cheat since I am basically calling Java, which is a decidedly server-side technology in this case.  I rationalized my way out of it. ANT is required to build the project, but knowing how to fire off an ANT build and being forced to right full Java are two different things.  I’d love to hear if any of you are put off by this.

Rhino gave me the ability to run JavaScript from the command line, or from ANT.  Since we publish whatever gets checked in to the github repository, and we publish that code through ANT, I could just reindex as part of the build whenever new content comes in. New content causes a reindex, the index is always up to date, and generated on my terms – only JavaScript.

What it actually does:

  • Reads in all HTML files in the site
  • Filters ones that I don’t want in search results.
  • Grabs the title, url, and content from each
  • Writes out this content to JSON on disk

It’s not perfect. Search is pretty primitive – I don’t know how far it will scale. But for now, I have a pretty cool solution to my problem.

Here’s the indexer code:

First New Contributor on

Wow, I’m happy to say we have our first new contribution to  Adam Tuttle fired off a pull request to me this morning to fix some grammatical and spelling issues. I was happy to bring his changes in.

This is a great example of how you contribute to Open Source projects you like without necessarily spending a tremendous amount of time or writing a crap ton of code.  Adam noticed some spelling and grammar issues, probably because I have the spelling ability of a Russian Sex Spammer. Awesome. He fixed it. He contributed it back.

I cannot tell you how happy I am to have someone correct me.  Feel free to pitch in.

I’m pleased to unveil a little project I’ve been working on for a few weeks now: is a reference site for answering the question “Which elements should I use to mark up this HTML semantically?” I’ve been joined in this effort by my coworker, Ray Camden. We’re pleased to put this out there, and eager to see what you can do with it.

The Story Behind It

I was (and still am) incredibly impressed by HTML5 Please.  I think it’s a fantastically on-target site. It showcases its technology and hits on a specific need and fills it brilliantly. I wanted to do something in the same vein without just copying it.  Around the time that I was feeling this, I got into an argument on semantics with someone. Specifically they were asking questions about when they should use article versus
div. Basically I explained what I knew of the spec for article. I gave some analysis, and made a recommendation.

When I was done with the argument I had an idea for a site:  A reference that would help people choose for themselves which tags to use semantically without being authoritarian.  I also wanted to set the tone that there isn’t one right answer to these things – that “semantically correct” isn’t a binary thing, but a position on a continuum.

The Technology Behind It

Another important thing for us in doing this was choice of technology. We placed a couple of constraints on the project:

  • We wanted to be open to other people contributing and offer a few channels for that.
  • No content management or wiki software
  • All code and content would be in HTML/JavaScript/CSS; no server-side technology

To achieve this we made a few choices.  To go open and collaborative without having a wiki, we went with github. Not the usual answer for a content site, but I think we can make it work.  The choice of no server-side tech (other than a vanilla web server) came about so as to not discourage contributions from anyone.  PHP, Ruby, ColdFusion, some JVM language, Python – whatever your back end, you have to know HTML/JavaScript/CSS. So let’s not skew one way, when most of the contributions can be made very simply with the front-end stack.

Working in those constraints wasn’t always easy. Ray got tired of copying and pasting template code around despite my incredibly stupid protestations that “No, it will be okay; we can work that way.” So he came up with a cool way to handle that with some JavaScript and .htaccess magic. I had to come up with a way to provide search without having any sort of server-side tech. We’re not sure if other people will be cool contributing under these constraints, but obviously I hope so.

Get Involved

We’re open to contributions.  We do all of the publishing through an automated build process that looks at the github repository for the project. So git is the path to getting on production.  We’re open to forks and pull requests.  We’re also open to contributions through email.  Basically if you want to contribute, drop us a line, we’ll figure out how to work with you to get you in.


Directory Listing in Rhino

This is pretty simple, but I couldn’t find it via searching, so I thought a little write up was in order.

I’m fooling around with Rhino, which is a JavaScript engine written in Java.  It allows you to do a lot, but in my case I am using it to write JavaScript helper scripts for ANT.  I’m working on a project for which I want to only write in HMTL/JavaScript/CSS.  I have to write some ANT scripts, but anything that I can’t accomplish with ANT, which means I need a scripting language to do, I decided to do in JavaScript.  Rhino allows me to accomplish that.

I’ll post more about what I’m trying to do when I release more about the project.  For this step, I needed to get a list of all of my files in my project so I could manipulate them in JavaScript.  I looked for a directoryList function, but only found this post on Directory Traversal. So I whipped up my own script for DirectoryList in JavaScript using Java on Rhino: