In 1952, the Boston Symphony Orchestra put up a screen during musician auditions to make them “blind”. They had been hiring more men than women and were trying to figure out if they were biased in their hiring. Still, the audition results skewed towards men. Why?
There’s a bar my wife and I like to visit near San Francisco’s Fisherman’s Wharf called The Buena Vista. They serve a delicious Irish Coffee. Even more memorable is Larry Nolan one of their frequent bartenders. If you go there during the week, sit at the bar. You might get a special chance to see Larry perform magic while you enjoy your coffee.
A few weeks ago my wife, three year old, and I travelled to the Bay Area. My sister-in-law just had surgery and we went to help with chores and recovery. Things like driving the kids to school, taking her to appointments, etc. We spent a lot of time visiting their neighborhood and local spots, so didn’t even make it into San Francisco to visit our favorite bar.
So it was a nice surprise to see a Buena Vista at the airport on our way back home. It wasn’t the same atmosphere of course, but at least we could get a tiny taste of our favorite San Francisco-esque thing.
When our waitress came by though, she looked grumpy we were there. Immediately I thought she wouldn’t be a very good waitress. We asked if they had chocolate milk, our 3 year olds favorite drink. She answered curtly with a flat, “No.” She wasn’t any friendlier while we placed the rest of the order. Great. Not only we do we not get to see Larry, but this waitress is terrible.
Minutes later the waitress came back with our Irish Coffees. But she had another drink. A giant bottle of Chocolate Milk. She said she went next door to the adjacent store because she remembered they sold chocolate milk.
What an incredible move. Blew me away. Very few people would go to that length to make their customers happy. My daughter was thrilled.
Maybe our waitress was just having a bad day. Or maybe that’s just how she is — not a lot of smiles or cheery conversation. But I took all those reads and turned them into an assumption that she was a poor waitress and didn’t care about serving us.
I couldn’t have been more wrong.
Of course men aren’t better musicians than women. So what was going on at these auditions?
The Boston Symphony Orchestra kept exploring how to make their auditions more blind. They asked musicians to take off their shoes before walking across the stage to their audition spot.
Bingo. The sound of the musicians shoes were giving away their gender. Audition results went to almost 50/50 men/women.
I had a chance to catch up with a friend of mine last week, Kurt Mackey. Today he runs Fly.io. At his previous company he instituted blind interviews. The system allowed for interview screening questions that involved code, but hid details about who the interviewees were. And the results were fantastic.
But it’s not just hiring. Bias and poor assumptions creep into everything we do. Look how wrong I was about something as trivial as ordering food at a restaurant. The whole experience humbled me in my ability to read people and showed me how poor some of my knee jerk assumptions are. It’s a huge reminder how much work we need to do to rid ourselves of biases.
I left that waitress a big tip.
P.S. You should follow me on YouTube: here, where I share more about how we run our business, do product design, market ourselves, and just get through life. Also if you’ve enjoyed this article, pleasehelp it spread by clicking the ❤ below.
Maslow had it wrong. To get it right, we have to move social needs to the bottom of his pyramid.
-Matthew Lieberman (Professor of Social Cognitive Neuroscience at UCLA and author of the book Social)
Babies would die without their caregivers at birth. Study after study show the pain and ill we go through when we are isolated from others like us. As humans, we are wired to connect to one another.
However, instead of connecting, we seem to be heading the opposite direction. On the streets and in restaurants people are looking at their phones instead of the person right next to them.
Businesses strive to make everything quicker, faster, and automated. Sending automated welcome emails with generic information to everyone who signs up. Introducing artificial intelligence to weed through support inquiries instead of having someone read and respond to your query.
It’s important to us here at Highrise to help people build great relationships. For many of our users, Highrise is an essential piece of that equation.
But what about us? How is our relationship with our users?
We try to make the welcome you get when signing up for Highrise a bit unique by changing the templates every day, asking people to chat, and a few other tweaks our CEO Nathan covers in detail here.
But we want to go even further. What else can we do?
Now, when you sign up for Highrise, you hear directly from me.
And by “directly from me”, I mean you see me, you hear me, and I address your individual needs based on what you’ve told us about you so far.
I personally greet you and ask you what you specifically need. And how we can help solve the problems you are having with your business.
The results so far have been really, really positive. And while making the human connection is the most important thing, we are hearing some really incredible feedback too.
First of all, holy crap. I’ve never gotten a video as a welcome message from a SaaS product before. I’m really impressed.
What an AWESOME email and video. Highrise is killin’ it! I really loved how personal this was.
Thanks Alison. I appreciate the thought and effort!
Hey Alison, that custom video for me was just mind blowing. Do you try to reach out to every customer that way? So impressed.
We are still a few weeks away from finding out whether or not these videos have an effect on our conversion rate. But one other huge factor is at play too: the memory of someone who cares. — Even if Highrise isn’t a good fit now, you may recommend us to friends, or even come back when the time is right. But most importantly, you might remember the human that took the time to make the connection with you.
As experts in helping people build great relationships, we keep learning too!
Ethan Marcotte on digital disenfranchisement and why we should design lightning fast, accessible websites:
We're building on a web littered with too-heavy sites, on an internet that's unevenly, unequally distributed. That’s why designing a lightweight, inexpensive digital experience is a form of kindness. And while that kindness might seem like a small thing these days, it's a critical one. A device-agnostic, data-friendly interface helps ensure your work can reach as many people as possible, regardless of their location, income level, network quality, or device.
A few of us at Basecamp were recently discussing how decisions get made to “green light” new projects, and I came to the conclusion that it boils down a simple rule:
If you can make a decision and you don’t think it’s going to get you fired, just do it.
Basecamp operates without much in the way of formal decision making processes. We don’t have a budgeting process, we don’t have program reviews, we don’t have long term detailed plans. There’s a vision for where we want the company and the product to be going, and a tremendous amount of trust that people will use their time and energy to move us in that direction.
The lack of those formal processes means it’s up to each individual to figure out what to do when they have an idea. The amount of implicit “decision making authority” differs for each person, depending on role, tenure, etc., but the same basic rule-of-thumb applies: if you aren’t worried that making the decision is going to be disastrous, you have authority to make it.
This works out because any decision you make is likely to fall into one of three categories:
You made the “right” decision and the company benefited, hurray! This represents the vast majority of decisions that are made at Basecamp, because we hire intelligent people and those people are making these decisions.
You made the “wrong” decision and nothing bad happened. No problem: as long as we learned something in the process, even a “wrong” decision is often worth the experience.
You made the “wrong” decision and something bad did happen. This is going to be ok too — at our scale, it’s hard for any one decision to be truly disastrous. We don’t have “bet the company” level decisions come up very often.
Our system of granting decision making authority — in which we don’t explicitly grant decision making authority, but let each person assert the level of decision making authority they’re comfortable with — is built on a certain level of trust. Jason and David trust that everyone who works here is smart, capable, and looking out for the best interests of the company, our coworkers, and our customers. In exchange, each of us trusts Jason and David that if we’re operating in good faith, we’ll be ok here even if we make a “wrong” decision.
In nearly seven years at Basecamp, I think I can count the number of times I asked Jason or David for “permission” to do something on one hand:
When I wanted to start running our first paid advertising experiments a month after I started working here.
In almost all of those cases, what I really wanted more than permission was advice. Does the way I’m thinking about this problem make sense? Is this course of action one that you think is likely to succeed?
The list of things that I’ve done without permission is much longer: I’ve committed us to tens of thousands of dollars a month in recurring costs to move our data infrastructure to the cloud, invested months of my time in projects that I thought were to the long-term benefit of Basecamp, launched new internal systems, added features to our customer-facing applications, gotten other teams to spend significant time on projects of my creation, and more.
In all of those cases, representing 99% of what I’ve done here, I either wrote up a plan and shared it beforehand, or I just announced what I’d done after it was completed.
This approach to decision making is well articulated by David Marquet in Turn the Ship Around as “Intent-Based Leadership”. Rather than asking for permission to do something, state your intent to do something and let someone object if they have concerns. Most of the time, no one has concerns, because you’re a smart, capable person who is going to make good decisions.
Having worked this way for nearly seven years, I can’t imagine working at a company where I’m asking for permission to do things every hour or every week or every month or even every quarter. Companies that limit decision making authority strictly do so at their peril — they waste their time worrying about who can make decisions rather than executing on them, and they drive away their best talent. One of our designers tells a story about needing five levels of approval to order a new mouse at a previous job; needless to say, he works at Basecamp now instead of there.
As of this morning at least, following this strategy at Basecamp has worked out for me — I haven’t been fired yet. I also didn’t ask for permission to write this post, and I think it’ll be ok.
I strongly believe that the documentation should be kept as close to the code as possible. Based on my experience, that's the only option that works well in the long term. External documents, notes, and wikis all eventually get outdated, forgotten, and lost.
Documentation is a topic that always bugs me. Working on poorly documented codebase is a ticking bomb. It makes the onboarding process a tedious experience. Another way to think of bad documentation is that it helps foster a low truck factor (that is, "the number of people on your team who have to be hit by a truck before the project is in serious trouble").
Recently I was on-boarded into a project with more than 1,500 pages of documentation written in… Microsoft Word. It was outdated and unorganized. A real disaster. There must be a better way!
I've talked about this documentation issue before. I scratched the surface not long ago here on CSS-Tricks in my article What Does a Well-Documented CSS Codebase Look Like? Now, let's drill down into the options for programmatically documenting code. Specifically CSS.
Similar to JSDoc, in the CSS world there are a couple of ways to describe your components right in the source code as /* comments */. Once code is described through comments like this, a living style guide for the project could be generated. I hope I've stressed enough the word living since I believe that's the key for successful maintenance. Based on what I've experienced, there are a number of benefits to documenting code in this way that you experience immediately:
The team starts using a common vocabulary, reducing communication issues and misunderstandings significantly.
The current state of your components visual UI is always present.
Helps transform front-end codebases into well-described pattern libraries with minimal effort.
Helpful as a development playground.
It's sometimes argued that a development approach focused on documentation is quite time-consuming. I am not going to disagree with that. One should always strive for a balance between building functionality and writing docs. As an example, in the team I'm currently on, we use an agile approach to building stuff and there are blocks of time in each sprint dedicated to completing missing docs.
Of course, there are times when working software trumps comprehensive documentation. That's completely fine, as long as the people responsible are aware and have a plan how the project will be maintained in the long run.
Now let's take a look at the most popular documentation options in CSS:
Knyle Style Sheets (KSS)
KSS is a documentation specification and style guide format. It attempts to provide a methodology for writing maintainable, documented CSS within a team. Most developers in my network use it due to its popularity, expressiveness, and simplicity.
The KSS format is human-readable and machine-parsable. Therefore, it is intended to help automate the creation of a living style guide.
Similar to JSDoc, in KSS, CSS components are described right in the source code as comments. Each KSS documentation block consists of three parts: a description of what the element does or looks like, a list of modifier classes or pseudo-classes and how they modify the element, and a reference to the element's position in the style guide. Here's how it looks:
// Primary Button
// Use this class for the primary call to action button.
// Typically you'll want to use either a `<button>` or an `<a>` element.
// <button class="btn btn--primary">Click Me</button>
// <a href="#" class="btn btn--primary">Click Me</a>
// Styleguide Components.Buttons.Primary
padding: 10px 20px;
Benjamin Robertson describes in details his experience with kss-node, which is a Node.js implementation of KSS. Additionally, there are a bunch of generators that use the KSS notation to generate style guides from stylesheets. A popular option worth mentioning is the SC5 Style Generator. Moreover, their documenting syntax is extended with options to introduce wrapper markup, ignore parts of the stylesheet from being processed, and other nice-to-have enhancements.
Other sometimes useful (but in my opinion mostly fancy) things are:
With the designer tool you can edit Sass, Less or PostCSS variables directly via the web interface.
There is a live preview of the styles on every device.
Who knows, they might be beneficial for some use-cases. Here's an interactive demo of SC5.
If you're searching for a simple, concise solution, mdcss could be the answer. Here's an interactive demo. To add a section of documentation, write a CSS comment that starts with three dashes ---, like so:
title: Primary Button
Use this class for the primary call to action button.
Typically you'll want to use either a `<button>` or an `<a>` element
<button class="btn btn--primary">Click</button>
<a href="#" class="btn btn--primary">Click Me</a>
The contents of a section of documentation are parsed by Markdown and turned into HTML, which is quite nice! Additionally, the contents of a section may be automatically imported from another file, which is quite useful for more detailed explanations:
Each documentation object may contain a bunch of properties like title (of the current section), unique name, context, and a few others.
Some other tools that have been on my radar, with very similar functionalities are:
Nucleus is a living style guide generator for Atomic Design based components. Nucleus reads the information from DocBlock annotations.
Atomic Design is a guideline to write modular styles, projecting different levels of complexity on a (bio-) chemical scale. This results in low selector specificity and allows you to compose complex entities out of simple elements. If you're not fairly familiar with Atomic Design, the learning curve may look a bit overwhelming in the beginning. The entities for Nucleus include:
Nuclides: not directly useable on their own styles (mixins, settings, variables).
Atoms: single-class element or selector rules (buttons, links, headlines, inputs…).
Molecules: one or more nested rules, but each of them is not more than an Atom
Structures: the most complex types, may consist of multiple molecules or other Structures.
The button example we use throughout this article here stands for an Atom - a very basic element of the stylesheet (single-class element or selector). To mark it as an Atom, we need to annotate it with the @atom tag, followed by the name of the component:
* @atom Button
* @section Navigation > Buttons
* .btn--primary - Use this class for the primary call to action button.
* <button class="btn">Click me</button>
* <button class="btn btn--primary">Click me</button>
* <a href="#" class="btn btn--primary">Click Me</a>
There is yet to be a clear winner in terms of a tool or a common syntax definition for programmatically documenting CSS.
On the one hand, it seems like KSS leads the group, so I'd say it's worth considering it for a long-term project. My gut feel is that it will last for a long time. On the other hand, different syntax options and tools like Nucleus and MDCSS look promising too. I would encourage you to try them on short-term projects.
It's important to note that all tools presented in this article might do the job well and seem scalable enough. So try them out and pick whatever makes the most sense to your team.
I'd appreciate it if you would share in comments below if you know or have experience with any of these or other tools worth knowing about!
In API Support, some of the trickiest questions we get are around how to authenticate to the Xero API. This is understandable. We use OAuth 1.0a for authentication which has a multi-step process in order to get the coveted access token.
To help clear some of the mystery around this process, I've created a quick video showing how to authenticate to a Public app using Postman. If you haven't tried Postman, it's a great tool for quickly testing out queries that can't be run through API Previewer, such as our new filtering we just announced. While we can't troubleshoot Postman for you, hopefully seeing it in action will get you started with a new tool for testing, and provide a better understanding of the OAuth 1.0a authentication process.