What is a JSON feed? Learn more

JSON Feed Viewer

Browse through the showcased feeds, or enter a feed URL below.

Now supporting RSS and Atom feeds thanks to Andrew Chilton's feed2json.org service


Allen Pike

A feed by Allen Pike


How to Write Docs People Read

Permalink - Posted on 2021-08-01 16:00

I like to write.

Well, I like to have written. And I especially like when people read what I’ve written, and find it useful. It brings me joy.

Writing useful things also helps me do my job. When you’re growing a team, you only get so far on oral tradition, habits, and institutional memory. When folks need to bug a senior team member to access your most valuable knowledge, it’s harder to level people up.

Given that, I’ve been spending more and more work time on docs. I’ve written docs about project management, client communication, hiring, architecture, 1:1s, product development, and dozens of other topics. It’s been really valuable for helping clarify our approaches to certain things. Concise, readable docs can give folks a big leg up.

However, I recently started to notice a problem.

I would gather input from our team on a topic, draft a doc on it, we’d iterate and refine it, and yay it’s great. But beyond that, it wouldn’t get referenced. Creating the doc would help us learn and refine our thoughts, but its value would too often stop there. A team would be waist deep in some tricky problem, and eventually I’d realize, “Wait. Isn’t this a problem we wrote about in our Project Management at Steamclock doc?” And we’d all sort of nod in vague recollection, not quite sure why none of us have have referred to that clearly written doc from a year or two back.

And if a doc isn’t being referred to, it’s not doing any good.

We already do a lot of things to help ensure our docs are useful: we make them short and sweet, well maintained, consistently formatted, and for the most part they’re on topics we’ve agreed are important. We work to organize them in an easy to navigate hierarchy in our Coda (think Notion but with more powerful automation and a bit rougher around the edges). So why was nobody referring to some of them?

The power of guides

My latest level-up on this came via Adam Avenir, who has led companies and teams for ages. He explained that the docs he’d written that were most often referred to had a theme: they were how-tos or checklists. Guides on how to get a thing done.

This struck me as powerful. Obvious in retrospect, as many powerful ideas are.

If a doc is clearly a guide for doing a certain thing, then people are a lot more likely to think of that doc when they’re doing that thing.

A team of individual contributors might be aware of “Project Management at Steamclock” existing, but are unlikely to prioritize re-reading it when a certain project management topic comes up. On the other hand, docs like “How to Prioritize Issues”, “Making Tough Decisions”, or “Run a Design Sprint” draw you in at the right time – the title tells you when the doc is useful!

Thoughtbot’s Playbook is mostly organized this way – you can sort of drill into it with a certain task in mind, and many of the docs are titled in a way that indicates what they’re meant to facilitate. And for the ones that aren’t titled that way, well – I’d wager that their page “Facilitating usability tests” gets more hits than the generically titled “User Experience Design” primer.

With this in mind, I’ve recently retitled and refined many of our docs to act more like how-tos and less like topic overviews. A couple months in, it’s already paying dividends. Not only is the team more inclined to navigate and refer to these guides, but they’re easier to write!

Mind you, a guide doesn’t need to be too prescriptive or constraining. You don’t want to bog down a thoughtful and creative team with a ton of policies that tell them what not to do. You do want to equip them with useful guides outlining how we typically do specific things, especially if those lessons were hard won.

And yes, from time to time it’s worth writing a primer, overview, or a thoughtful exploration on some key aspect of the business. In practice though, the docs your team will reach for most are the how-tos. Guides that help them do something.

In order to help encourage this style of doc, without discouraging less formal notes and docs, we now distinguish between a Guide and a Note in our doc “How to Start a Guide”:

  • Guides are nice docs we’re maintaining with the goal of them being concise and correct. This is most often worthwhile for “how to” docs that will be referred to more often than they change.
  • Notes can take any other form, and are great for capturing knowledge from a specific point in time: meeting minutes, findings from research, results of a brainstorm, a project update, etc. These are generally docs “as of $date”

Growing a team is all about iteratively putting yourself out of a job. You teach people how to do what you do, so you can go and do the next layer up of broader, trickier, or more uncertain work.

Sometimes all you need to do is write out how to do something, so talented folks can pick it up and do it – then do it better.

Amazing Atelic Activities

Permalink - Posted on 2021-07-01 16:00

Early in one’s life, it’s easy to be driven by goals. Pass the test, get the grade. Get a job, buy a car. Get into university, finish university. Get married, have a kid. There are a lot of things to do!

While the specific goals vary from person to person, our lives start out with a lot of low hanging fruit. Things that haven’t been done, but are clearly worth getting done. It can be a big motivator.

At a certain point though, perhaps in your 30s or 40s, this loop becomes less satisfying. The most straightforward goals have been achieved, and the most ambitious goals are starting to look, uh, ambitious. Even when you’ve done what you set out to do, it doesn’t feel quite right. “I’ve achieved all these things. I’m successful! Why don’t I float through each day radiating the tranquil joy of an accomplished human? Why do I still sometimes wake up feeling, a little bit, like a duffel bag of shit?”

Of course it’s well known that that achieving goals doesn’t directly make you happy. I learned the phrase “Life’s a journey, not a destination” all the way back in 1993, when it was coined by noted philosopher Steven Tyler. But it took 26 years for me to actually do something with this information, when I read an essay from Ed Batista that put me onto this idea, titled “Not Every End Is a Goal (On Midlife Malaise)”.

I was initially hesitant to read an article about midlife crises. I’m not even 40 yet. I have neither the inclination nor the time to have a crisis, let alone a midlife one.

And even if I did, what an embarrassing privileged white guy thing to do. People are out there – as we speak – fighting for their rights, fighting for their lives. Meanwhile I’m sitting here like a jackass thinking, “Hm, checking off these OmniFocus tasks isn’t giving me as deep a sense of self actualization as I’d imagined; what is my path to lasting purpose?”

Still, checking off those OmniFocus tasks really wasn’t giving me as deep a sense of self actualization as I’d imagined. So when that article put the following very useful idea on my radar, I was primed to receive it. Perhaps it will help you too.

You can divide how you spend your time into two categories..

  1. Telic activities. Things whose purpose is the end. Drive home. Have a wedding. Unclog a drain. Ship an app.
  2. Atelic activities. Things whose purpose is the middle. Explore the forest. Listen to music. Tinker with something you enjoy.

The problem for ambitious people comes when we load up on telic activities. We push ourselves to check things off and get things done, and feel perhaps guilty when we’re not getting anything done. There’s gotta be a balance.

And that ideal balance tends to shift as you get older. Your youthful focus on telic activities – things you’re glad to be done with – ideally adjusts over time to more atelic activities – things you’re glad to be doing.

This isn’t a secret formula to guarantee a purposeful and fulfilling life – that can only be achieved by playing a very 90s VR game where you watch a guy play a similar VR game about motorcycles and making out and… weird 3D dogs? But I’ve found it helpful.

Honestly, even just being thoughtful about when I’m doing something for the sake of doing it has been nice. I walk a little slower when I’m just going for a walk, I’m a bit less focused on finishing games, and I’ve been getting better at enjoying the parts of my job that I really enjoy – in the afternoons, once I’ve checked off the thing that really needs doing.

It’s amazing.

The Teams You Worked on May Have Sucked

Permalink - Posted on 2021-06-01 16:00

As we grow at Steamclock – we’re now at 14 and hiring our 15th – we’re getting more intentional about how we do things. I worry less about how to do the work, and more about how to build the team and our processes.

Which is great. But it’s a problem set that is a bit more… ambiguous. We want to constantly improve. But how do we separate the big opportunities from the stuff that’s just inherently annoying?

There’s a sentiment I sometimes hear when we’re considering these kinds of problems:

Well it’s not great. But we’re already better at this than any company I’ve worked at before.

Which is nice to hear – we’re already the best! Phew. Maybe it’s just a hard problem, and nobody’s great at it. We can just move along and… wait a minute. Waiiit a minute.

We’re better at this than any company you worked at before. But how did things go for those companies? Poorly enough that you left.

Do they even exist anymore? If they do, presumably they’ve gotten better. If not, they’ve been replaced by leaner and smarter competitors. Meanwhile, we’re comparing ourselves to companies that couldn’t retain great team members. We’re ignoring the existence of the teams that are out there kicking ‘tocks, and defining the new standard for how ‘tocks can be kicked effectively and profitably.

Of course the past experience of our team members is invaluable. But we need to be actively researching what effective teams are doing nowadays. Find people who work at companies that do great work. Read what they write. When you can, build a relationship where you can share what you know and they can share what they know. Don’t let yourself feel smugly superior to the last generation of companies.

Benchmark yourself against the folks kicking the most ‘tocks.