My Philosophy of Technical Writing

I said earlier on twitter that I like interviews because it gives me a chance to talk about my philosophy of technical writing and how I’d go about implementing it. Good friends reminded me that the ideal way to talk about one’s philosophy and implementation is while being paid a respectable hourly rate. That is very true! I have cut off interviews that I felt were exploitative.

The problem is that most business and development people don’t exactly understand what a normal technical writer does, much less a technical documentation architect with a heavy sideline in technical speaking. If I want to get a position that fits me, I have to explain to them why they need it. I don’t worry too much that I’m cannabilizing my own business because it’s so general that even my implementation details would be hard to implement without a grounding in the disciplines I used to construct them. Offering people a taste of my thinking is only going to whet their appetite.

A luscious pomegranate

Core principles

  • No one wants to be reading documentation.
  • Technology is a means to an end, not an end in itself.
  • Users experience technology differently than creators.
  • Answering questions is more valuable than comprehensive information.

Seems straightforward when I say it like that, right? But every one of those principles is something I learned the hard way, carved out for myself, watched in action. No one taught me that. Many people contributed to my thinking, but it is my synthesis that matters here.


At the highest level, implementation is about interrogating why we write documentation at all. Could we solve it with better workflow? UI text? Detection? Scripts? Is there some way we can change the technology so that a user is not angry enough to go look up documentation?

If they are forced to look up documentation, how fast can we answer their question? We live in a world where you have been able to use natural language search for most of a decade. We need that to be true for documentation, too. “How do I configure this on Solaris?” “What’s the curl command for oAuth”? Don’t make people look for something, just…give it to them. This answer is deceptive. It sounds very simple, and implementation is a complicated blend of search, SEO, writing, and metadata. But not all beautiful things are easy.

If you can’t use something, you shouldn’t have to write about it. If you have to take the way software operates on faith, then are you really documenting it, or are you just transcribing the unverifiable claims of engineers? There are a lot of things that you can’t run, or can’t fully run, or can’t run in production, but there are lots and lots of things that you can hack through enough to test it and see whether the steps make any sense at all.

What do you call something you can’t use, can’t improve, and can’t answer questions about?


A lot of my implementation philosophy comes down to not documenting vaporware. Vaporware is not the exclusive domain of hip new startups, it can happen anywhere, to the most established or productive of companies. I once started a job with a multi-billion dollar company, only to quit it 4 days later when I realized they were not clear on whether they were making an app or an API. That is not a scenario where documentation is going to help.

The projects I like best have the following features:

  • I can use it.
  • It solves a problem (I’m not great at documenting games)
  • It has very little existing documentation, so I’m starting fresh instead of retrofitting.
  • It has a deadline.

Those are personal preferences, and I almost never get all of them, but it’s nice to know what makes you happy.


I can tell you what I think about documentation at great length, and I can explain what makes good and bad documentation depending on who your audience is. Given enough time and consulting fees, I can tell you how to fix your documentation, or I can fix it for you, or I can create it new from first principles. My next set of goals is teaching developers to write more practical documentation, and figuring out how to teach other writers to work like this.

(Current goals: Give a keynote speech, get paid to teach a workshop)

Lady Speaker CFP Submissions

The way one becomes a Lady Speaker is by speaking. That’s pretty obvious. But how to do you get someone to give you a stage and a microphone and an audience? That’s what this post will partially cover. Specifically, how do you submit a talk proposal?

Find decent conferences

There are lots of places you can find conferences. My three main sources are the @callbackwomen twitter account, the Technically Speaking newsletter, and I also hear about conferences just generally on twitter.

Conference proposals are some amount of time before the conference, it depends on a bunch of variables. For example, the CfP (Call for Proposals) for LISA 17 just went out (mid-January), and the conference is the start of November. 3-6 months is a more typical window.

In addition to finding out what conferences are soliciting speakers, you need to find out if it’s a conference you want to speak at. My criteria are:

  • Has a good Code of Conduct
  • Has not mishandled a Code of Conduct violation in the last 3 years, that I know of
  • Understands I am providing value and deserve value in return
  • Is not promoting scary values

Let’s unpack those.

Good Code of Conduct

There have been a lot of things written on Codes of Conduct, and I don’t want to rehash years of debate. I heavily favor codes of conduct that are derived from the Geek Feminism model, but almost anything will work as long as it bans specific bad behavior, does not require (but allows) legal intervention, does not make victims do confrontation, and has actionable and specific enforcement clauses. Basically, my ideal code of conduct allows someone to make a private complaint to the conference and the conference will listen to the victim about how they want it handled, but also have a plan for dealing with a known set of bad behaviors.

Did you heckle a speaker? The conference will give you a warning once, then kick you out. That sort of thing. Having a set of unacceptable actions means that you don’t get people saying “I just said she would be even hotter wearing only a lanyard! It was a compliment! How is that not “being excellent to each other?”. Almost everyone has had corporate harassment training at some point, so people do actually know what they are and aren’t allowed to do in professional settings.

Mishandling CoC violations

Before you apply to a conference, google them. See if there is any recent uproar about them having a known-predatory speaker and not doing anything, or if they made a panel on women in technology out of all men, or if people of color are warning each other away from the conference. Sometimes you will find out that a conference screwed up and then fixed it, like Nodevember did this year by disinviting a speaker. But if they screwed up and didn’t fix it or didn’t apologize, it’s probably not a safe conference, no matter what the CoC says.

Value exchange

The first year I did conference speaking, I did it on my own dime. The second year, I got paid a couple times, but nothing like what I needed to cover expenses. The third year (this year), I only applied to conferences that said they covered speaker expenses. I had sufficient videos and experience that I was not an unknown quantity, and also, I could not afford to speak the way I wanted on my own money.

I wrote about this more in Don’t ask me to work for free, a reprise. But basically, a conference’s value derives from speakers. A speaker invests extremely heavily in researching, writing, and rehearsing a talk, and then in lost work time to give it and attend the conference. Conferences shouldn’t charge a speaker to attend. If it’s at all feasible, conferences should at least cover travel and lodging. I apply to a few conferences that charge speakers, but they also heavily subsidize anyone who doesn’t have an employer. The only thing more insulting than a conference charging me for giving away my intellectual property is a conference offering me a DISCOUNT on the registration fees. That tells me they know I’m providing value, but it’s not worth THAT MUCH.

Value match

I don’t attend conferences that I think are problematic because of their values. I don’t go to Grace Hopper because they make a lot of money off women but don’t really do a lot to nurture women’s work, especially women of color. I don’t attend conferences that are about exploiting labor. I wouldn’t, for instance, attend a conference focused on defeating ad-blockers. Your values are your own, but I’ll tell you from experience that if you show up at a conference where you are already angry at the premise, the experience you have will be stressful.

Promise them something useful

I’ve been on talk selection committees, so I have a fair idea of how it goes. The first thing that happens is there is an elimination of the obviously not-useful talks. These are usually vendor-tools talks, talks that are not the right technology, or talks that are described by a single sentence and a speaker bio that says, “You know I’m awesome!”.

What I want to see is a novel idea (it doesn’t have to be brand new), that will serve my conference attendees, and let them walk away thinking something new or interesting or making a connection they wouldn’t have had otherwise. Your CfP needs to have a value-proposition. A lot of the submission forms now explicitly ask for that, which makes it easier.

I also want to know that you understand who the target audience of my conference is. If you’re submitting to a security conference, a Password-Keeper 101 talk is not going to be relevant. If you’re submitting something that seems odd in the context of the audience, you’ll need to justify it. For example, I’m a technical writer who speaks at a lot of developer/coder/devops conferences. What do I know about that? I have to explain that to even make it past the first level.

Once all the easy choices are made, the selection committee will get down to the rest of the talks — they would like to accept almost all of these, but time and space are remarkably fixed, so instead they talk about whether you have experience, whether this group of proposals covers the same idea, and if so which is the best one. They weigh the advantanges of fresh voices agains known winners, and the disadvantages of anxious speakers against same-old-same-old. And yeah, they talk about money, and whether they should select someone local or someone who has to be paid to come in. People advocate for speakers they know, or recuse themselves from deciding on speakers they know. Hopefully, someone looks at the overall balance of the speakers and tries to make sure it isn’t like this.

This list of speakers is a little worrisome

I’m not trying to shame this one conference, but hopefully conference runners are trying to find a speaker lineup that looks more like this:

© Katura Jensen 2016

Assembled @theleaddev speakers.
Photo: © Katura Jensen 2016

If you want to be a speaker at a conference, it’s going to take hard work from you to pitch, write, and deliver a talk. And it’s going to take good luck, because there are a lot more talks than slots. And it’s going to help quite a lot if the talk selection committee isn’t using some pre-established vision of what a conference speaker looks like.

Make hard choices

If you get accepted to a conference, that is SO GREAT.

When I get an acceptance email, before I write back and confirm, I double-check (or ask the first time) about what the plan is for speaker expenses and fees. Like I said, I don’t have an enterprise behind me, so I try not to donate my time for free very often.

If they can’t pay you, and you can’t afford it, you have to decline.

If you have already accepted something else in that slot, you have to decline.

If it’s across your kid’s birthday party, you better negotiate to bring home a really amazing souvenier.

Sometimes, even when everything seems like it will be great, you get hurt and have to write the conference organizer at the last minute and say you can’t come (Sorry, @seagl!)

The key is to tell the conference what is going on as soon as humanly possible. Because the thing they’re going to do is pull up the next speaker who was regretfully turned down and ask them if they can fill in. The longer you delay because you feel bad about saying no, the less time you’re giving the next person to be able to say yes.

There’s also some stuff in here about making sure you have some time to work and see your family and eat food that you make yourself, but that’s Lady Conference Speaker 301, and I’m still at 201 myself.


I could write pages and pages on how to write and deliver a talk, but the important things are these:

  • Show up prepared and practiced
  • Respect the work of the audience and organizers
  • Stick to your time limit
  • Work the hallway track

Prepared and practiced

This is not a term paper. You can’t write it the night before. You need to have said this thing out loud in front of an audience at least twice. Once so you can figure out what you’re trying to actually say, and once for timing. I usually practice my talks 5 times for a new talk, and 1-2 times if it’s a talk I’ve given before and revised. You are commanding the attention of, say, 50 people. For a technical audience, let’s say that they are worth $50/hr. You need to respect that for this moment, this half hour, you are worth AT LEAST $1250 in attention. How much work would you have to do to feel prepared to earn $2500/hr? Do that much prep work.

Respect the work of audience and organizers

It’s hard to sit in a conference chair all day and learn things. It’s physically and mentally exhausting. Even on days I’m not speaking, when I’m through with conference sessions, my brain is full, my legs ache, and I just want to take a nap. The audience is paying attention to you, even if they are also thinking about how what you’re saying relates to their job, and worrying about their accumulating email. The audience deserves your respect.

The organizers, whew. If you’ve never organized an event with hundreds of people, I’m telling you, it’s eye-opening. There’s all this trivia to deal with, everything from making sure the t-shirts arrive, to making sure people don’t get in without badges, to taking care of speakers who are having technical problems. Someone has to make sure the catering sets up right, while simultaneously reminding everyone of the code of conduct and answering the hotel’s question about when the tables can be set up. Odds are, the organizers won’t get to hear your talk, because they won’t get to hear anyone’s talk. They’re too busy making it happen for us. Do what you can to make their lives easier by communicating with them clearly and succinctly.

Stick to your time limit

It is a jerk move to exceed your time limit. The audience needs those 5-15 minutes to get to the next talk, possibly with a bio-break on the way. The next speaker wants to get in and set up and make sure the mic is ok. The organizers are praying the schedule doesn’t go awry in one of their rooms.

I know myself well enough to know that my talks inflate when I get in front of an audience. There’s just something that happens when I have people reacting that makes me go longer. So I always time my talks to run 5 minutes short of the limit, and I assign someone to wave frantically at me at 10 and 5 minutes before the limit. Some people talk faster in front of an audience, but an audience will always forgive you for going 5 minutes short, but not 5 minutes long.

Work the hallway track

After you give a talk, a funny thing will happen. For the rest of the conference, people will recognize you. They’ll stop you in the hall and say they liked your talk. Don’t argue with them, although that is the natural instinct of many of us who were raised to be “modest” and “not brag”. Just say, “thank you” if you’re on your way to something else.

If you have time, you will make this person’s day by stopping to talk with them about your content.

  • How will it apply to your work?
  • Was there anything especially meaningful?
  • Do you wish I had included something further? I did lots of research that didn’t make it into the talk.
  • What would you want added if you could hear this again?

These questions are a combination of engaging them in talking about their reaction, and figuring out how you can do it even better the next time.

Also, when people give me compliments on my talk, I tally them up at the end of the day and email the tally to myself, because sometimes I need to open that kind of email. “22 people stopped me to compliment my talk today” has a way of kicking Imposter Syndrome in the ass.

NOTE: At no point are you required to talk to someone who is being insulting, argumentative, or creepy. Giving a talk is not the same as giving up your right to ignore people.

In conclusion

I believe in you. You are going to go out there and make us proud! And you’re going to do it by talking about things that you want to understand, or want other people to understand. I hope you can find a good mentor in your community, but if you can’t, reach out and find one online. Some conferences even offer explicit new-speaker mentoring, which is great!

Hidden Figures, Shine Theory, and Being Friends with Women

I saw Hidden Figures this week, and I happy-cried at least three times during it. It is a blatantly heroic story about very feminine expressions of power. There is a trickster, a paladin, and a wizard, and although they each have their own missions and their own tribulations, they do it all in immaculate lipstick, lovely pencil skirts, and a deep sense of community.

I realized as I walked out that this movie reminded me of Shine Theory:
Briefly stated, Shine Theory is about rejecting the idea that there are a limited number of high-acheiving positions available to women, and lifting each other up instead of competing. There is also some evidence [PDF of academic paper] that smart kids are more likely to hang out with each other.

Essentially, this gif:

An animated gif of women offering each other a boost in turn.

Libby Vanderploeg’s “Lift Each Other Up”

I posted this on Twitter, and my friend Tiberius says that she worries about “burdening” the women she admires, and drew a connection between that feeling and Imposter Syndrome. “Oh, she’s so cool, and she must be super busy and I shouldn’t take her time with my trivial stuff”.

I said that I had learned a lot about overcoming this because I have some amazing friends who have taught me disability/feminist theory. (yay intersectionality)

“Instead of picturing one another as rough equals making a bargain, we may be better off thinking of one another as people with varying degrees of capacity and disability, in a variety of different relationships of interdependency with one another”

— Martha Nussbaum


Notes on being a woman trying to make friends with amazing women

This is an expansion of the thoughts I tried to condense into tweets. If you want the shorter version, the Storify is at the bottom.

1) You have the capacity to be amazing

I think few of us understand our full potential, because even if we are working to our maximum while we are in isolation, we get some amazing synergies when we are together. This is part of why it’s so important to me to attend and mentor at conferences. I learn so much from just interacting with other people.

2) Amazing women have just as much potential to screw up as anyone else

The tendency to idolize people we admire is terrible, because it means when they inevitably have a moment of awkward humanity or even cruelty or stupidity, we have to question our whole belief system in them as admirable, instead of acknowledging that they made a mistake and are still amazing.

This does not apply to people who are deliberately hurtful or cruel, or even accidentally but repeatedly hurtful in the same way. Don’t be around someone who hurts you regularly.

3) No one knows what they bring to a friendship, nor does it stay constant. We are all too rich to have only one channel of value

Have you ever had a friend who makes amazing talk slides AND can get her eyeliner to do perfect wings? Do you want to learn only one of those things from her, or can you broaden the ways you share with each other? I don’t always know what people get from friendships with me, but I trust them to allocate their own time according to their own priorities. Maybe I’m just that good at baking cookies, who knows? I don’t have to know. It is enough that we are all astonishing in our own ways, and those ways sometimes help other people.

4) Toxic culture makes us think friendship is transactional. It’s not, it’s about interdependence, the state of graceful giving and receiving

Giving and receiving sounds transactional, but if you get deep into the sociology weeds, it’s not the same. Transactions are always conducted with one’s own benefit in mind. Giving is an act of centering the other, and receiving graciously is something between other-centered and lovingkindness to yourself.

Have you ever had a friend bring you anti-emetic when you are really, vilely sick? Even if they push it through your mailbox, you still feel loved and cherished, because they have taken the time to do something for you that does not require reciprocation. It’s just something they do, because they’re your friend, and they are not thinking about the cost of the medicine or the time spent getting to your place, they are thinking about how much they love you and hope you feel better soon. Someday, you may do something similar for them, but not because you owe them for that one act. You do it because she’s your friend and she needs help.

5) Most people, and especially women, are more limited by time and resources than we are by capacity to love and care. We can still be friends with someone we only talk to once a year

I’m not going to go into the whole feminist theory about why it is women have less spare time and spend more of it in emotional labor. It’s a thing and you’ll have to trust me. Because I have these obligations, I cannot always spend the time I would like nurturing my friendship. Luckily for me, I have several friendships where we see each other once a year, and are happy to see each other, and have a high degree of relational intimacy (in the communication studies sense), but I just don’t make time for them in the course of my ordinary life, because I don’t have that kind of time. That’s ok, as long as everyone is consenting to what I call “episodic friendship”.

6) To make a friend, start by being genuinely friendly. Mutual disclosure and trust will come in their own time, or not. That’s ok.

You can’t make someone be your friend, any more than you can make a romantic interest want to date you. But you can signal that you want to spend time with them, and you can think of very low-level nice things to do for them that don’t seem excessive or grandiose.

Good: Handing a speaker a sealed water bottle. Asking for a business card. Offering to share a seat at a table.

Excessive: Flowers. Skywriting. Attending every presentation they attend.

Mutual disclosure is an escalating set of self-data that people match until they reach their intimacy level. Usually in professional settings, this includes: name, job, career, neutral affiliations, and possibly family status.

If someone doesn’t feel like telling you about themselves, that’s ok. They don’t have to, but they probably don’t want to be your friend then, either, and you should leave them alone.

7) Almost everyone you are talking to is thinking much more about how they are screwing up this conversation than how you are. Our inner voice is our harshest critic. Remember that when you are talking to someone poised and brilliant, odds are she is still being human and a little worried.

We’re trained to be self-aware when we’re talking, so that we’re not rude. Sadly, many many times this spills over into people spending fully half their brain cycles trying to determine if they are sounding like an ass right this second. A quarter is going to what they are saying to you, and a quarter is going to what you are saying to them.  If they DO notice you seem awkward, they may wish they could help you, rather than judging you, because they realize that they could be the awkward ones at any moment.

Sadly for all of us, the people who are actually jerks are almost never spending their processor power in self-critique and anxiety.

8) Friends are like radio stations you find as you drive across the country. Sometimes they fade out. This is normal and not bad.

You can tell I grew up in the American West, where driving through an FM station is an event, but not a remarkable one. We don’t need to keep all of our friends with us for all of our lives. If we keep growing and changing, our friend needs will, too. We’ll make new friends, and the old ones will mostly drift out of our lives, with a few exceptions. I see so many people agonized by the loss of these relationships, but it seems like they are actually worried about being a bad friend, not about growing up and moving on.

9)  If someone consistently makes you feel worse about yourself – grubby, coarse, ugly, dumb, a charity case? They are not your friend.

All of us need a friend or two who will tell us we’re being jerks. But if you know someone who doesn’t seem to believe you’re amazing, and in fact treats you like you are not as good as they are? They are not a friend.

Friends love you and lift you up and want you to be your best. It’s not punitive, and you don’t get punished for being a loser. You just get loving help and faith. If you are trying to be friends with someone who punishes you, or makes you feel shitty, leave them when you can, because they will not make you shine.

10)  I have amazing friends. They are brilliant, kind, witty, quiet, steadfast, handy, anxious, snarky, nurturing, curious. Thank you all.

I am so fortunate in the women I’ve added to my life. (and also the guys) They encourage me, give me courage, copy-edit my work, help me brainstorm, bring me medicine when I need it and babysit the kids so I can go on a date with my spouse. I just hope they also feel as loved and seen as I do, so that we can all shine on.

Response to: Modern Technical Writing, by Andrew Etter

I’ll be honest. I’m a little mad I didn’t write this book. It’s clear, lucid, and pithy. I agree with much of the philosophy of minimal tooling and semantic separation of form and content.

Etter says,

Great documentation makes new hires productive in days instead of weeks, prevents thousands of calls to customer support, is the difference between crippling downtime and rock solid stability, and inspires true, fervent love of development platforms.

To which I say, yes, yes! I’ve been saying, speaking, thinking, writing the same message. It’s so much more efficient to have good docs. I also agree that good technical writing (about software) is mostly about testing and research, and the time spent with the product should get distilled down into an understanding and then and only then transmuted into words.

He also says that it is much easier to answer the how of software, rather than the why, but you must answer the why to really write something useful. His points on lightweight markdown, rapid publishing, and internationalization are all exactly on-point.

My quibble with this book (and it is only a quibble, not a full-fledged criticism) is that there is a section missing, and it is the section on user motivation. You can write the most beautiful, terse, lightweight, well-indexed documentation in the world, but if you’re not driving toward what the user needs in every sentence, they’re not going to read it. The user doesn’t want to be reading documentation. Reading documentation is the opposite of doing something interesting with software. It’s filling up the car before an amazing road trip, it’s an impediment. And until we as writers realize that, we’re going to continue to write too much, for the wrong people, at the wrong time.

Etter is very clear up front that this is only about software documentation, as practiced in software companies. But there are a lot of people in technology, the majority of people in technology who don’t work building software per se.

It’s not Etter’s fault that we forget this. We have build ourselves a cozy little ecosystem, and if I told you I worked for a company doing Hadoop or containerization or financial APIs, you would understand that I worked for a software company. But I have also worked for a health insurer, a social media empire, a durable goods manufacturer, a commodities broker. I wrote about software, I wrote about our products, I made decisions about security and metadata and the location of quick start guides – as a technical writer. There’s a big non-software world out there that we keep forgetting to talk to and learn from.

What would this book look like if we didn’t assume that software was a service, that our users were relatively computer-savvy, that we were not the only kind of writers in the world? I keep coming back to this article by the Nielsen Norman Group: The Distribution of Users’ Computer Skills: Worse Than You Think. Jakob Nielsen, trenchant and brilliant as usual, points out that we keep designing things for ourselves, and we are really, terribly, fearsomely wrong about that.

You = Top 5%–8%

The main point I want to make is that you, dear reader, are almost certainly in the top category of computer skills, level 3. In the United States, only 5% of the population has these high computer skills. In Australia and the UK 6% are at this level; in Canada and across Northern Europe the number increases to 7%; Singapore and Japan are even better with a level-3 percentage of 8%.

Overall, people with strong technology skills make up a 5–8% sliver of their country’s population, whatever rich country they may be coming from. Go back to the OECD’s definition of the level-3 skills, quoted above. Consider defining your goals based on implicit criteria. Or overcoming unexpected outcomes and impasses while using the computer. Or evaluating the relevance and reliability of information in order to discard distractors. Do these sound like something you are capable of? Of course they do.

What’s important is to remember that 95% of the population in the United States (93% in Northern Europe; 92% in rich Asia) cannot do these things.

You can do it; 92%–95% of the population can’t.

What does this simple fact tell us? You are not the user, unless you’re designing for an elite audience. (And even if you do target, say, a B2B audience of nothing but engineers, they still know much less about your specific product than you do, so you’re still not the user.)

I’ve seen people take this argument and assume that means we need to produce more videos, and I think that’s the wrong assumption. I think that what Etter, and I, and you, need to do is remember that the world is bigger than “software development” and writing for the people in the big world is the next level, something we have to strive for, rather than staying in our small and shrinking tidepool of high-tech and software.

Guest post: SysAdvent!

I wrote a pitch for SysAdvent and got it accepted, and then realized that it was due right in the middle of all my travel, so it’s a good thing my volunteer editor was willing to work with me on the timing.
Day 17 – Write It Down or Suffer the Consequences

This article has a lot in common with my Fear of the Bus lightning talk, but I have a little more time to flesh out the ideas and connect them. I hope you enjoy my take on how to do minimally invasive documentation for systems and not just software.

SysAdvent Logo

SysAdvent Logo

Publish and pull managers

@kwugirl has done some great work around ask culture and guess culture (, and how frustrating it can be when you are framing communication the wrong way so that you are constantly rubbing on someone. 

Ask culture says that it’s ok for someone to make a direct request for a favor, and it’s equally ok to tell them no. Guess culture is more face-saving. A request in guess culture would look like a hint or ignorable indirection when translated to ask culture. Corporate America tends to default to ask culture because of… a lot of reasons.

But ask and guess culture are about making requests of someone who has power to grant them. How do we want to talk about this when we are dealing with our managers? They want things from us, we may or may not have the ability to grant them, but the power differential is all different. 

 I think of this in terms of internet architecture – publish vs. pull. 

Some people work best for managers who provide regular feedback and consistent updates on what’s going on in the manager/employee relationship, the project, the company as a whole. The publish manager will tell you regularly how you’re doing without needing any prompting.

Some people work better for pull managers. When they have a question, they can ask and get an instant answer on how things are, but on the whole, the relationship is much less focused on status updates either direction, and much more on blocking disruption. The manager exists to protect the time and autonomy of the employee, and the employee doesn’t get much direction unless they ask for it.

Of course, neither of the methods is bad or good, they just are. The problem is when you have a mismatch between the method a manager uses and what the employee uses or is comfortable with. 

For example, if you’re a pull person, all that feedback and mentoring and goal-setting and communication feels like noise or even micromanaging. Getting status updates all the time feels like an expectation that you should be doing more. And on the flip side, your non-communication feels to a publish manager like you’re not doing anything, or worst-case, that you are deliberately concealing problems. Why won’t you disclose, why do they have to pry your status reports out every week?

If you’re a publish person, and your manager only talks to you when you ask a direct question, and they put off status meetings if there’s nothing really important to talk about, you get kind of paranoid. What terrible things are they hiding? Are they angry with you? You sent in a report and you didn’t get any feedback on it, was it bad? What’s going on up there? A pull manager with a publish report will appreciate that they know what’s going on, but they consistently forget that their taciturn default causes actual anxiety in this person. Everything’s fine until you say otherwise, so what is this about?

Ok, so it’s yet another binary to divide the world into, like the introvert/extrovert oversimplification. What does it mean for your actual life?

Now that I’ve realized this, it’s changed the way I interview. Of course, we don’t always get to pick our managers, but at the moment when you do, ask the questions. 

  • “Do you prefer to update people on a schedule or when they ask?”
  • “How does your most successful report communicate with you?”
  • “What’s your favorite kind of update meeting?”

You don’t want it to be too leading, because when someone is interviewing you to be their report, they really want it to work out, at least if they are the kind of person you want to work for. When they are in the room with you, they are thinking how to work you into their team, their workflow. They’re trying you on, including your communication style. And it’s their job to work with you, so they might unconsciously bend to meet your preference if you make it too obvious.

If you’re a manager, the same thing applies. A candidate might be perfect in every other way, but if it seems like you’re going to have to ask them every week for their updated status report, or if they are going to want a ton of feedback from you and you’re a more hands-off person, you may want to add that to your decision matrix and decide if that’s an amount of effort you’re willing to expend on negotiating your natural communication style.

We can all work with people who have different communication styles. We do it all the time without thinking about it. The best plan is to do it mindfully and patiently, realizing that most people are not actually trying to make you irritated or confused with their style, and that your style may be hard for some people.

Guest Post on

I was supposed to be at SeaGL this weekend for an awesome conference with the opensource world. Sadly, I fell in the garage and dislocated my shoulder, so I can’t attend. On the bright side, the post I wrote to promote my talk at the conference is available!

Four Steps to Better Documentation

In it, I talk about a few simple steps to making sure you are writing the documentation that people need, and making it as relevant and accurate as possible.


Tech events and alcohol: a proposal

I was just at a conference, which was much like any other conference in their after-hours events. The food was pretty good, the beer and wine flowed freely, and the mixers were Coke, Diet Coke, and sparkling water.

There’s a lot of complicated parts of throwing a conference, especially in a hotel, and each of the events had professional bartenders. This means the conference is not devoting someone to handing out alcohol, the hotel has some belief people will get cut off, and it all works great. If you want to drink.

But more and more, as I go to these things, I wonder why we want to drink. I mean, seriously. We are here to have high-level conversations with the leaders and up-and-comers in our fields. That is not improved by artifically lowering our IQ or our inhibitions. As a woman, I am especially sensitive to the fact that it is extra dangerous for me to appear drunk, when statistically, at least one of the men eating cheese and wine in this room has not been great about consent with an intoxicated partner. As a person with migraines caused by time-shifting, lack of sleep, and sulfites, alcohol is not a great idea if I want to keep performing at peak efficiency.

What could the conference spend this money on instead?

  • Paying for more under-indexed people to attend.
  • Paying speakers
  • Providing childcare
  • Paying open-source maintainers
  • Really excellent pop selections (Mmm, Fentiman’s)
  • Space for other organizations that can’t afford it
  • Community support/outreach

I want to be clear that this is not about any one conference. In fact, the one I went to, I didn’t see any sign of misbehavior. I just think that the economics of it are counter-productive and reinforce existing power structures. I hope that in 20 years, we will feel about the open bar at tech events the way we feel about the smoke-filled room today. It’s a thing people can do, but it’s not a requirement to network.

What is the advantage of providing free alcohol?

  • People who care about free alcohol are happy

They are a big demographic, don’t get me wrong. But I don’t think that anyone who would refuse to go to a dry conference because it was dry is someone who is likely to be in a position to add a lot to the conference. That’s a pretty hard line to take when you can always buy a cocktail in the hotel bar 50 steps away.

For more on this topic, read:

Model View Culture: Planning Tech Events with Non-Alcoholic Options

Let’s Talk About Alcohol At Tech Events

Does Our Industry Have A Drinking Problem?