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.