Documentation for DevOps: A DevOpsDays Open Space Writeup

I’m borrowing this image from my friends at Chef, because it’s really funny to pretend that it’s possible to just sprinkle on “devops”, something that is about cultural change at every level.

At every DevOpsDays I go to (and that’s quite a few), I propose/wrangle/run two open spaces. One is about feature flags/canary launches/hypothesis-driven development, and the other is this one, which I usually refer to as “Docs for DevOps”.

DevOps documentation is difficult because it’s not intended for external audiences, so it’s hard to make a case for hiring a writer, but it’s also mission-critical, which means that it can’t be ignored or neglected.

I also have a talk that I give on this topic. You can find recordings from DevOpsDays Minneapolis and NDC Minnesota here. but this is specifically about the open space. I am indebted to a number of people in the last year who have come to open spaces, shared their experiences, asked questions, and challenged my thinking and assumptions.

I’ve grouped the questions I hear most often into these categories:

  • How can I find anything?
  • How do I get people to read the docs?
  • How do I get people to write the docs?
  • My team is small, do you have particular advice?
  • My team is very large, what should we do?
  • Distributed team best practices?
  • Why is sharepoint?
  • What tools are most useful?

How can I find anything?

Frequently, the first problem that people have is not that nothing is written down, but that lots of things are, and the problem is discoverability and accuracy. It’s one thing to have instructions, and quite another to have instructions that you can find when you need them. Many people have their operations documents spread across one or many wikis, ticketing systems, and document storage platforms.

The short answer to this problem is “search”. That is also most of the long answer. The thing I think we overlook is that we don’t have to use the search engine that came with our wiki. We could put something else in front of it. With the demise of the physical Google Search Appliance, you still have a number of service options. Most of them will give you the option to index and search multiple sites.

As a consultant who helped companies structure documentation so it was usable, I have a lot of specific advice on how to change the architecture and the culture, but honestly, if you could get your company to hire someone to help with that, you could probably get them to hire a writer and solve the problem another way.

The last part of this answer is that you could get some consulting dollars and hire an archivist/librarian to help you come up with tags that help identify the types of data and make it easier to search for. When we’re trying to recall data, we frequently do so by keyword or tag, and an archivist can help you make a canonical list of what people should use for that.

How do I get people to read what we have?

First, see above, make it easy to find.

Second, make it as easy as possible to read. Sit down in a group and hash out what type of information has to be included to make a topic/article/page useful to others. Once you know what you need to have included, you can make a template so that people remember to include it all.

The next problem is to figure out how to point people to the documentation without being dismissive or making them feel like you are too good to answer their questions. This might be a good place for a chatbot, or a single web page full of resources.

Many people would rather be able to find an answer themselves than bug a coworker to get it, so if they’re not reading the documentation, there’s probably a systemic problem blocking them.

How do you get people to write the docs?

Do you know any sysadmin or SRE who has ever been fired for lack of documentation?

Do you know of anyone who has gotten promoted solely on their ability to write internal documentation?

Most of us don’t. No matter how much organizations say they care about documentation, they are not putting anything of meaning behind those words. It’s not malicious, but it does tell you that documentation is not actually something they care about.

One of the ways to fix this is by using a reward system. Buy a package of Starbucks cards, or awesome stickers, or ice cream certificates, and give them out every time someone completes a documentation task, immediately. Adding a tally mark for their eventual review is much less motivational than immediate rewards for work. You don’t have to be a manager to do this – anyone can motivate their co-workers. The reward doesn’t have to have cash value, but I do think it’s the easiest way to indicate your appreciation.

Another thing to pay attention to is how easy or hard it is to write the documentation. If it’s a complicated system, the barrier to entry is high. If it’s in a tool the team already uses, in a language they already know, it’s much easier to persuade them to drop in a few lines. if there is a form for them to fill in so they don’t have to figure out what they are supposed to include, that’s even better. Lowering the cognitive barrier to entry is as important as the tool barrier to entry. After all, we’d have a lot more trouble writing bug reports if we had to write them out by longhand without any fields to fill in. Documentation is the same way.

My team is small

Consider using just one single page of truth. No, seriously. If you’re working with a team under 8, and especially if they’re distributed, consider just putting everything on one single web page and searching it when you need to find something. The overhead of managing a documentation system or wiki is not something you need when your team is that small. As you write new things, they go at the top and older stuff gets pushed down to the bottom and becomes obviously less important or relevant. If you need to find something, you can easily search the page. No one has a secret pile of documents that the rest of the team doesn’t know about. It’s not an elegant solution, but it’s hella utilitarian.

My team is large

Hire a writer. And/or a librarian. I was talking to someone whose IT organization was over seven thousand people. They obviously do need some structure, some tooling, some information architecture. Rather than spend internal IT cycles on it, I suggest hiring experts. There are thousands of people in this world who are trained to manage, collate, write, and wrangle large sets of documents, and it’s wasteful to try to do it by yourself.

What are the best practices for distributed teams?

Pretty much the only effective way to have a distributed team is to change the team culture to one where you write down questions and answers, instead of popping by to share them. It’s important to make sure that key data is always written down and not passed on by word of mouth, because as soon as you have an oral culture, you are leaving remote members out.

It’s useful to have at least one team member working remotely who has distributed team experience. You can ask them for what has worked for them in the past and enlist their help in iterating your practices. For example, is it hard for the team to remember to set up the call-in for meetings? Change the meeting template to include a shared meeting room automatically. No one gets a distributed team right immediately, anymore than we do a colocated team. It’s just that it’s easier for distributed teams to end up in a broken state before someone notices.

Why is SharePoint?

Because the paradigm and core analogy is filing cabinets. “What if I could see inside the Operations filing cabinet?” Because it thinks of itself as a way to organize pieces of paper, it’s not very good at documents that need to be shared and altered simultaneously across organizational boundaries. It was a marvel for its time, a way for non-technical users to get their documents out of shared drives and file cabinets and give other people regulated access, but it is fundamentally hostile to searching.

What tools are most useful?

It depends, right? Tools exist on a sliding scale between absolutely zero barrier to entry on one end and and taxanomic usefulness on the other. Every team must find their own best place, which may not be the same across the company. But if a team dislikes a tool or finds it burdensome, they just won’t use it.

The best tool is the one you can get people to adopt. If your team is 100% people who know how to use LateX and created their resumes and gaming character sheets in it, then it would be a fine tool. If you had a team composed entirely of people under 20, maybe a a youtube channel would be the way to go. Since none of us have completely uniform teams, the best thing we can do is to find a tool that everyone can grudgingly agree only sucks a little bit.

In conclusion

  • Use a better search engine
  • Hire experts whenever possible
  • Make it easier to write things by using templates
  • Iterate and keep improving your devops docs process. There’s no solution, just a fix for now.

2017 Speaking Recap

This was the year that I got more organized as a speaker. I took up Airtable as a way to track all of my conference proposals, and so I actually have a record of everything I submitted.


  • Attended 27 conferences, spoke at 24
  • Spoke at 3 user groups, 2 podcasts, 1 video interview, 1 twitch stream
  • 14 unique talks, in a variety of configurations
  • Learned to use Twine as a presentation tool, how to give demos on an ipad over lunch, how to change from saying “I’m a technical writer” to “I’m a developer advocate”

Portrait of a white woman with pink hair, wearing a black and white dress and grinning at the camera

Longer version

Continue reading

Talk write-up: Choose Your Own Deployment

Yesterday, I was in Phoenix for their first DevOps Days.

The interesting thing about doing this talk in Twine instead of my beloved Google Slides was how much I had to learn to make it look anything like I wanted. There’s a lot of CSS and Twine-specific syntax. At first, it felt like I was wasting my time and being slow because I know other people know this better than me, but as the project went on, it was honestly delightful to learn something new and get my pages to look like I wanted. There was a lot of fist-pumping success in getting a font to work.

It’s still not perfect, and I need to do some pretty drastic revisions for version 2, but now I know which of the resources are most useful to me and I have a conceptual model that I didn’t have when I started, so I think it will be easier to learn the parts I still don’t have.

It’s been a long time since I’ve had to learn something that had immediate tangible results, instead of concepts and pitches and taking what I already know and distilling it down. It was good to do that, and I should remember to schedule it into my life sometimes.

Lady Conference Speaker Talk Wrap-Up

I was talking to Bridget Kromhout about her wrap-up process, and she inspired me to a) do a better job publishing my talk information right after I give it, b) talk about my end-of-talk process.

So, you have pitched a talk, gotten it accepted, written it, gotten on stage and given it, and answered any questions. You are about to come down off the adrenaline high and start second-guessing what it is you said. It is totally normal not to be able to remember exactly what came out of your mouth. Depending on how nervous a speaker you are, you may not have formed any particular memories, because we are terrible at forming coherent memories when we’re scared.

The slot after your talk, or the evening after, or the flight home, you want to publish your talk wrap-up. I think the ideal wrap-up consists of the following elements:

  • Your slides
  • Twitter reactions
  • Follow-up answers
  • Research sources/bibliography/image sources
  • Video

I do almost all my slides in Google Slides, with Slides Carnival. I do a new set for each talk, since I’ll end up adjusting length and emphasis for each conference. Immediately after I give the talk, I tweet out the public link to them. My slides also have extensive speaker notes.

The next few steps are much easier if you use Storify, an app that plugs into your browser. When I am researching a talk and have a reasonable belief that I’ll be using a page as reference, I click the Storify button to add it to my potential elements. I can also use it to capture tweets that will be relevant. After my talk, I’ll open Storify and look for tweets about the talk, whether with my Twitter handle, the conference hashtag, or the talk hashtag. I drag all the relevant tweets into the story about this talk at this conference, organize them, and then add the link to the slides at the top and the reference elements at the bottom. Then I click publish. I can always go back and edit that Storify to add the video when and if it’s ready.

In WordPress, Medium, LinkedIn, and several other platforms, you can embed Storify stories as part of the post, to raise the visibility and make sure it’s part of your platform as well as Storify’s.

Keep an eye out on your email. Conference organizers are quite likely to ask for your slides so they can sync them to video or publish them on the conference site.

There are a couple places that I want to improve my process — I have seen webpages that have two columns – one for the text of the talk and one for the slide. I feel like that would improve my web presentation and make it more accessible, but I have yet to find the WordPress/CSS magic to make it happen. Everyone I know who does it has hacked their own, and I want a turnkey solution.

I also want to start dedicating some money to getting talks professionally transcribed. What I write out and what I actually deliver are similar, but not identical, and again, I want to improve access for people who can’t or don’t want to watch video.

Here’s an example of one of my talk writeups:

Screen capture of the front page of a site using folksonomy

Human Indexing

One of the consequences of cheap storage is that we have no incentive to reduce the amount of data we keep. We believe that we’re going to be able to search for whatever we want. But we are starting to exceed our human capacity to filter the returned results of our searches. Algorithms will help us some, but they are never going to be enough as long as we keep adding data at this rate. We’re going to have to use metadata to help us find anything.


For centuries, we have organized data taxonomically. All living creatures have a place in the Linnean structure. I am a chordate, a mammal, a primate, a human. There are lots of library organization systems that organize books and information. For example, the Library of Congress system has categories for everything, and room left for categories of knowledge we haven’t found yet.

Taxonomy has several problems, though. For one thing, you can only sort something into one bin at a time. Constraining things into only one category means you may not think to look in the correct places and assume that the information doesn’t exist.

Taxonomy also replicates the power structures of the culture that makes the organizational, which can be problematic. For example, there was a time when the Library of Congress system categorized Native Americans as fauna of North America. It’s always going to be dangerous to underrepresented groups to encode knowledge as the domain of a dominant group. And even if it’s not dangerous, it’s othering and discouraging.


The solution that has been arising lately is called folksonomy. Folksonomy is assigning tags to a piece of knowledge, based on the contributions of many individuals. You’re already using folksonomy in more places than you know. For example, Amazon recommendations uses both taxonomy and folksonomy to drive recommendations, and so does Netflix. We use it as individuals many times we are trying to describe something that we don’t know the exact name of.

The value of folksonomy is that it doesn’t depend on a top-down organizational system. Instead, it builds an understanding and description of something from many different perspectives. Like the parable of the six blind men and the elephant, the elephant may seem very different to you based on your perspective. For example, records of the Salem Witch Trials might be about early American history, or about Puritans, or about the suppression of women’s expression, or about the racism involved. The records don’t change, but their category and description does, according to who you are, what your perspective is, and what you are seeking to teach or understand.

The downside of folksonomy is that humans are sometimes terrible, and if you leave any system of public contribution completely open, people will attempt to spoil it or use their voice to dominate it. Imagine if every instance of a book that contained Christianity or a reference to communion got deluged with hundreds of tags about cannibalism. It would become difficult to find anything that was actually about cannibalism, and most people looking for documents about Christianity would find their results pushed farther down.

The other problem with folksonomy is one of standardization. If people can freely enter tags, they will enter very slight variants. Not intentionally, but it’s just extremely hard for anyone to be perfectly consistent, let alone many people. If tags vary, then they are not useful for grouping things together, because “King Arthur” and “Arthur, King of the Britons” will not be returned together, even though he is the same historical person. Conversely, “Shaun” might return you an adorable claymation sheep or a zombie-fighting slacker. You’d need to disambiguate them to get clear results.

Tag-Wrangling and Transformative Works

The organization that I have seen balance these conflicting values best is called Archive of Our Own. AO3 is a non-profit organization devoted to hosting transformational works. Transformational works are anything that takes a source text and tells a new story, or alters the text to convey a new point of view. Because US copyright law is not yet very clear about transformational works, this is also united with an academic journal and a lobbying movement to promote the idea of transformational works as a legitimate artistic expression.

Warning: Although nothing in this post is explicit, the AO3 site hosts many sexually explicit works. I do not recommend visiting the site on a monitored system or if you choose to avoid sexually explicit material.

AO3 uses a combination of taxonomy and folksonomy to make hundreds of thousands of fanfic stories available to people who are looking for them. Users can search by story title or author, or they can step through to increasingly fine categories, such as Movies->Marvel->Captain America->Winter Soldier. Stories are then further sorted on pairings, if there is a romantic element.

Screen capture of the front page of a site using folksonomy

AO3 fandom sorting page

Authors can give stories tags. These tags frequently convey authorial commentary, or appeal to a specific in-group of readers. They also function in a descriptive role. For example, a story might be tagged:

  • Odin’s A+ Parenting
  • Thor/Hulk
  • Thor/Banner
  • Loki (Marvel)
  • Thor (Marvel)
  • Hulk (Marvel)
  • LGBTQ Character
  • Humor
  • Drama
  • Curtain fic
  • Longfic

These tags are a mix of authorial description and comment (Odin’s A+ Parenting, Curtain fic), and “canonical tags”, which are standardized tags which describe specific characters or media sources (Loki (Marvel)). If you just searched on “Loki”, you would get both the Marvel version and the mythology version. “Python” returns both Monty Python and snakes.

Searching “loki python” gives you a relatively small overlap.

Tagging also includes warnings about types of content that people find distressing. Being able to select tags away means that people will never be accidentally exposed to something they work to avoid. The community has agreed on a general set of things that will either be explicitly warned for or the whole story will be assigned “Author Chose Not To Use Warning Tags”, which means there could be anything in there, take your own risks.

The canonical tags are managed by a small army of volunteers known as “tag wranglers”. These amazing humans standardize common tags and character and source tags, and also group together similar tags. For example, if you click on the tag/link “Odin’s A+ Parenting”, you’ll see a Tag Page:

The tag wranglers have collated similar and related tags and grouped them together so that reader’s searches have more chance of success. For example, I’m American, so when I am sarcastically assigning an excellent grade, I say “A+”. But British fic-readers might instead say, “Odin’s A-level parenting”. They mean the same thing, but you would have to have an EXTREMELY well-trained machine learning system to link that, or you would need humans. Tag wranglers also work to maintain and standardize warning tags.

The Art of Indexing

One of the early influences on me as a technical writer, before I knew technical writing was a thing, was reading Kurt Vonnegut’s Cat’s Cradle. Mostly, it’s a story of apocalyptic greed, but there’s a throwaway passage:

It appeared that Clair Minton, in her time, had been a professional indexer. I had never heard of such a profession before. She told me that she had put her husband through college years before with her earnings as an indexer, that the earnings had been good, and that few people could index well.

The idea of that passage stuck with me, the thought that indexing is an art worth paying for. When I became a technical writer, I was pretty junior, and ended up with the boring assignment of generating indexes. FrameMaker made this easy enough by parsing out headings to create index entries, and I even had a tool that would permute the headings for me, so I would get entries for Shaving the Cat and Cat, Shaving. But I was unsatisfied with that result, because it was just about the headings, and sometimes I was missing key concepts, so I had to go through and do manual indexing anyway.

So often, when we say indexing now, what we mean is a concordance, not an index. A concordance is a straightforward listing of all the places a word or phrase appears in a document. An index is more carefully constructed, and only points to useful instances of a phrase or word, like introductions or significant mentions. A really good index will also include words that never appear in a document.

User language is not our language

For example, if I show you this picture

Windows Blue Screen of Death

you probably identify it as the Blue Screen of Death. But until about 5 years ago, you would not find that phrase if you searched the Microsoft website. If you had the problem, you would need to search on “fatal exception”. It’s deeply unsatisfying to look for help and not find it. Even now, you won’t find a Microsoft help page about it on the first page of Google results.

If we want to serve our users, we need to meet them where they are, using the language that they use. So if they call something a spinning beach ball or a blue screen of death or whatever, use it in addition to the name that you call it.

The point of indexing something is to make your product and documentation easier for people to use. If you are not using the language that they use, you’re only writing the documentation and index for people who already work for you.

You won’t be able to imagine the names that people call your product (hopefully good). You’ll find their words in the places that they are helping each other. Stack Overflow, user groups, mailing lists, the files and reports that your own support team keeps.

Once you’ve collected all the language that people are using, you need to roll it into your index. You don’t want to identify every instance of a phrase, only the ones that actually pertain to the answers people are looking for. You want people to get the answer, not a deluge of partially relevant information.

Attach the index tags to the place with the best solutions, and also the meta tags that you want to include in the index. For example, if you have a heading called Activating your Thromdimbulator, you will want the following index tags associated with it:

  • Activate thromdimulator
  • Turn on thromdimbulator
  • Activate thingy
  • Turn on thingy

That’s the human indexing effect. There is an index entry that has zero words in common with the heading but will still be exactly what someone needs if they think of their thromdimbulator as a “thingy” that they want to “turn on”.

Human indexing is hard, because it takes time and knowledge and deep product and industry knowledge. But the reward is that even in our search-oriented, automatically-generated world, an excellent index is going to set your product apart.

This post is an expansion on a lightning talk I gave at PyConAU 2016 and Confoo Montreal 2017.

Cassandra at the Keyboard: Whistleblowing and Working

I originally gave this talk at Open Source Bridge 2015. I then almost completely rewrote it and gave it at Write/Speak/Code Chicago in 2016.

Content notes

This essay will contain references to the following topics. If that’s something you prefer not to read about, I totally understand:

  • Discussion of sexual harrassment
  • Discussion of sexual violence
  • Discussion of intimate partner/domestic violence
  • Discussion of online stalking/abuse
  • Adult language


If you’re here to learn about the database, I’m sorry. This is the other one.

I named it after a mythological character who was cruelly cursed to provide perfectly accurate prophecies AND NEVER BE BELIEVED.

I think Cassandra is the patron of whistleblowing because no one decides to upend their life for a lie. Whistleblowing is a painful and dangerous process, much like telling ancient Greek kings news they don’t want to hear.

Whistleblowing: A definition

For something to be whistleblowing, it needs to have all of these qualities.

  • True
  • Actionable
  • Expensive or painful to solve

If something is true and actionable, you are asking for a reasonable improvement, there’s no problem.
If something is true and painful, but not actionable, there’s nothing anyone can do to fix it.
If you are reporting something you know is untrue, your organization is not what needs repair.

When I say painful, I mean that the problem is going to be hard to fix, because it’s expensive, or because it damages a person or company’s self-image, or because it will require behavior changes from a large number of people.

Reducing carbon footprints, admitting doping in sports, and recalling cars are all examples of painful actions.

Also, when I say whistleblowing, there is an implied power differential – this is not a thing that happens in mutual relationships, but from a less powerful person to a more powerful person or organization.

Whistleblowing is not reporting something because it affects you, but because it will affect other people. Vengeful reporting may be justified, but it’s not always the same thing as whistleblowing.


So you have noticed something is very wrong.

You are sure it is happening.

There are actions that could fix it, if someone had the will to take the actions. You are not sure anyone will choose the right thing to do over the status quo, because the action will be very difficult.

What can you do?

from Google Books

Exit, Voice, and Loyalty, a book about choices by Albert O. Hirschman

In 1970, Albert O. Hirschman wrote that when a person sees a decline in quality from their organization, they can either choose voice (complaint) or exit, but that loyalty affects that binary choice to make it a three-way decision. Your loyalty affects how you choose to exit or speak up.

For example, have you ever been attached to a brand and disappointed when they screw up, like when Lands End took two belt loops off the back of their plus size jeans? You can either write them and complain, or you can silently take your business to Eddie Bauer. But if you have a lot of loyalty to Lands End, you’re more likely to give them a chance to fix their mistake by telling them about it.

These balancing decisions frequently occur in combination in whistleblowing cases. A person can see a problem, voice it, and then remain loyally silent if it is not repaired. Eventually, they may feel that they need to leave. Voice, Loyalty, and Exit are not a one-time decision, but an ongoing tension in our decision-making.

Let’s make this less abstract. Here are three examples from my life.


Do not plagiarize the American Medical Association. This seems like an obvious rule for living, but I was put in a situation where my manager directly told me to “file the serial numbers off” some documentation from the AMA. I felt…unhappy about this and asked if we could get permission. He said no.

Rather than repeat my protests to my manager, or just go ahead and do it, I went to the CFO and explained why this was a violation of my professional ethics and could get me, personally, sued, as well as the company. The CFO took my report seriously, and I ended up in a call with a terrifying lawyer from New York who probably billed by the second.

The CEO got my manager to back off, and it was mostly ok. But even though that is a best-case scenario of how to handle whistleblowing, this guy was still my manager, still didn’t believe he’d done anything ACTUALLY wrong. I left as soon as I could, because it was so awkward working as his direct report.


Have you ever wanted to stand up at a wedding and say, “For the love of God, don’t do it”? I have.

I spent the week before my brother’s wedding trying to deny to myself that I was worried about his choice. I thought that maybe I was being overprotective of my little brother, that I just needed to let the bride find her feet in my family. I chose loyalty over voice, over saying something.

As it turns out, it was the wrong choice, and she was the wrong fit, and maybe it would have saved everyone some court costs and time and heartache if any of his loving and loyal family had said, “Yo, you know you don’t have to get married, even if we have the dress right here, don’t you?”


Anyone wanting to see which way I incline in this system has only to look at my LinkedIn history.

I leave. I see problems, and I say something, or I don’t say anything, but I leave. I leave as well as I can in the circumstances I have, but I get out of Dodge. This may seem like cowardice. It may BE cowardice, but I don’t have the energy to stay and fight it out every time. There is an enormous mental and emotional cost to convincing an organization they have a problem.

Most recently, I fired a client because I believed they were selling something as a security solution, when it was in fact only an access control solution. I tried voice, but when that failed, I left instead of staying for what I felt was the inevitable crisis when someone was breached.

Bigger examples

My examples are relatively small-scale. I’m lucky that way. Let’s touch on some other people who have made the voice/loyalty/exit choice on a larger scale.


Whistleblowers can be women who stand up to abusive rudeness, like Sarah Sharp.

Sarah Sharp

Sarah Sharp, Open Source Hardware Developer, General Badass

Sarah was a Linux kernel developer when she decided to request more collegial interactions on the Linux Kernel Mailing List, which could have upwards of a thousand messages a day.

Linus Torvalds said,

“I’d like to be a nice person and curse less and encourage people to grow rather than telling them they are idiots. I’m sorry – I tried, it’s just not in me.”

Network World said,

Sharp has publicly locked horns with senior Linux kernel developers including Torvalds in the past over issues of civility and professionalism, and has, arguably, been more responsible than anyone else for pressing the community to consider those issues more critically in recent years.”

There are people like this, who have chosen to take their whistleblowing public, and are suffering very real consequences for it, but who are also moving the conversation by their very presence, their stubborn refusal to shut up about it already.

We don’t all have to be that someone. We don’t have to admire all of whistleblowers on a personal level. We don’t even have to like them. But we can see that this is what voice looks like, if that’s a path we ever feel we need to follow ourselves.


When I was thinking of examples for this section, I was struck by how many of them were masculine.

Oh, I thought. The culture of military and sports bonding promotes loyalty over speaking out.

  • The NFL’s coverup on traumatic brain injuries.
  • Lance Armstrong’s US Postal cycling team full of doping.
  • The Charge of the Light Brigade.

Then I realized which women were engaging in loyalty and silence — women in abusive and unsafe relationships.

Frequently, by the time a woman starts thinking of leaving to save herself, she is tied to the abuser by loyalty, by children, by financial dependence, by emotional abuse. It’s too easy to say that people in abusive relationships should just leave. We have a strong human urge to team up with people we love, who say they love us.


There are a lot of people who have left, and for the most part, they have chosen not to be famous about it.

They decided to spend more time with their families. They went into a second career. They found another job. I don’t think it’s right for me to use most of them as examples, but the one really core to me is Kathy Sierra.

She was viciously abused and threatened, and because of that, she gave up her online presence, and much of her speaking and teaching career for five years. She stopped teaching people Java and user empathy and spend healing time with her Icelandic horses, who have never been known to dox anyone.

Photo by Kathy Sierra

Kathy Sierra takes heartbreakingly good pictures of her horses

Her exit was public, clear, and painful for a lot of us to watch.

Real Talk

Let’s talk about what’s going to happen if you choose to exercise voice.

You’re likely to get fired

Not for reporting harassment, but because you’re not a good fit, or a bad team player, or just not fitting in. The worst part is that the people telling you this will actually believe it’s true.

There are federal whistleblower protections, but once you’ve been fired for reporting someone, you are probably not excited about working with them anymore, and invoking the protections involves getting a lawyer, and and and. So there’s that.

You’ll take a reputation hit

Depending on how big a splash you make, or who you are pissing off, you may come under online or offline attack, you may suffer professional damage, you may get a reputation as someone who is in it for the drama, or a tattle. Just as women in an industry talk to each other about unpleasant men they deal with, men gossip about who is difficult for them to deal with. It will feel like everyone is calling you a bitch.

One of the first responses a lot of people have to a report of harassment is to tell the victim to toughen up. You remember that Medium post where the woman said, sure, guys had tried to kiss her at conferences, but it wasn’t a big deal, she just talked more about her husband and her kids and made sure to leave parties before midnight? Yeah. It’s not just men that will come down on women who report harassment. It’s also women who have had their own run-in and have chosen loyalty, for their own reasons. Choosing otherwise challenges them in really uncomfortable ways.

You won’t feel vindicated

Even once you speak up, you are not necessarily going to get the outcome you want. That’s frequently outside your control.

People can report rapes, but they can’t jail rapists by themselves. They can report embezzlement, but they cannot get the money restored. They can report harassment, but they cannot change a company’s culture.

If you are going to be crushed if nothing changes, you may want to consider Exit more heavily.

Why speak up?

That is all pretty dire, isn’t it? This is not the same talk I would give to people with less experience, but I’m guessing that very little of this is news to you. [Note: I was giving this talk to a room of senior/experienced women]

So let’s talk about why people make the choices they do about whistleblowing.


Either the whistleblower loves the system so much that they can’t bear to see this grit in the gears of something good…

….or they are so bothered by the apparatus of the system that they want to throw a wrench in the works — the original sabotage.

In any case, this kind of motivation is usually about a long-term problem.


The problem you see matters to other people – people like you or people you care about.

Think of LeAnne Walters, who went to the Flint City Council and then the EPA about the water in her house. It’s not just that she had a problem, it’s that if she had a problem, then other people would too. Environmental concerns are probably the easiest for us to generalize as being for the sake of humanity in general.

Something is going wrong and people are being hurt, and our whistleblower can’t stand that. The whistleblowing invokes the power of someone who has more capacity to stop bad things from happening to people.

Ideals and rules

Say something because your ideals are being violated. Ideals can include things like patriotism and faith, or even the image of ourselves as “good people”. Chelsea Manning leaked documents because she felt that the world needed to know what the US was doing, because it conflicted with her understanding of what it meant to be American/patriotic to keep quiet.

Say something because you are following an ethical or legal structure that requires it. This is why we have mandated reporting for people who work with children. You are given the support of legally not being able to keep questionable things to yourself if you are a mandated reporter. You have to tell someone.

Know your reasons for speaking up. It makes it easier to be clear about the outcomes you hope for.

Why keep quiet?

This is not an idealistic talk. I am aware there are lots of reasons a person would choose not to be a whistleblower. Let’s talk about some of the common reasons people decide that the risk is too much.


Sometimes, your truth is not worth as much as the ability to live indoors and eat food.

Sometimes you need to weigh the benefit others will get from your speech with the harm you may experience. Lots of us are sole wage earners, or we don’t have the ability to walk away for some other reason.

In my family, we say, “Mommy can’t go to the beach with you. Someone has to earn the money to buy the yogurt.” This example is grimmer by the day as my kids turn into teens!


Maybe it’s important to your self- concept to keep a secret.

For example, Chelsea Manning’s co-workers did not reveal classified data, even if it conflicted with their personal ethics, because they had sworn an oath to keep it secret.


The most important reason not to tell your story is because you don’t owe it to anyone. You are not required to live out your pain for other people to see. You are not required to report a rape if it doesn’t serve your needs. You are not obligated to speak up at detriment to yourself.

No employer is as important as you are, your whole self. If it would serve your organization and harm you, you don’t have to say anything.

Exit, your other option

Odds are, at some point you’re going to have to leave. Either your organization won’t change, or they will push you out, or you don’t feel that you can stay any longer without saying something.

What are you going to do about it?

Go quietly

There are two ways to leave. The first is to leave quietly, to take the exit interview and say you’re moving for a better opportunity, to bite your tongue, to get out as cleanly as you can.

This is a perfectly valid, reasonable, and respectable decision.

Burn it all

The other way to leave is like an action movie hero walking away from an explosion.

You go in to the exit interview and lay out the whole truth. You email the details to the paper of record. You embrace your identity as a troublemaker and you make sure everyone knows why you are making trouble. You (gasp) tell the truth on Glassdoor.

You’ll burn some bridges. It’ll be awkward to get references, or maybe even your next job. But you can pick voice and exit simultaneously.

Practical advice

Do what you can with what you have. Know your reasons and your (probable) consequences.
Whatever your reasons, you should identify them and make sure that your plan takes them into account, so you meet your actual goals. Why are you doing this? Systems? Empathy? Ideals?

There are always consequences for invoking power. It’s a little like summoning a demon. You are never the most powerful person in the relationship, by definition. So before you say anything, you have to try to establish what the likely consequences are, and whether they change your opinion of what you want to do.

Depending on the level of what you want to say:
Talk to a friend
Talk to a lawyer
Talk to people who will be affected

Are you ready to go? Do you have a box under your desk, do you have your computer all cleaned up, do you have your parachute packed? Exit is what you do on your own terms, but depending on how serious the thing you are speaking up about is, you may get asked to leave anyway.

Audience matters

You want to invoke some external power, but you need to figure out how the most appropriate person is. Telling the wrong person could be worse than silence.

Power: They need to have power — the power to change something, or to bump the problem up the ladder. You need them to be someone who can do something about your problem that you’re reporting.

Authority is the external trapping of power, but it is also the way that your actions will be legitimized. When I refused to plagiarize the AMA, I went to the CFO to report my boss. Although the CFO had the power to tell me I had done the right thing, and to connect me with the expensive lawyer, it was only when he told the CEO that my boss was reprimanded. I had chosen someone with power, but not the right kind of authority.

Sympathy: Choose someone with sympathy. They don’t have to be sympathetic to you as a human, although that’s nice. They need to be sympathetic to your reason for telling. Are they systems people? Are they empathy people? Whatever it is that drives them needs to be something you address when you tell them.

Go in with a solution

Choose someone who can act on your report. Choose someone as a partner for change, with the power and the psychological profile of being a ‘fixer’.”

Especially in workplace situations, if you go in and complain, you are a problem. If you go in with a solution, you are an asset. People may not take your suggestion, but that’s ok, at least you have offered a way that they can think about solutions.

The worst thing about getting a reputation as a complainer is that it’s easier to think of YOU as the problem, and if they get rid of you, then they don’t have a problem anymore, right?

It’s all about the money

Choose someone who understands how this change will contribute to the financial health of the company.

The great thing about whistleblowing at a company is that it is almost always true that your disclosure will save them money in the long run. You just have to get them to understand that scope. Are you going to save their product from being delayed by programmer communication issues? Will this action keep them from being sued? Could the company avoid a superfund site-level of expense? Will a change improve the productivity of a team that is no longer dealing with the mental expense of micro aggressions?

Businesses have a hierarchy of needs, just like we do. They want to stay alive. So part of successfully disclosing is convincing the organization that it’s a matter of life and death.

Protect yourself

With any form of whistleblowing, you run a risk, but here are my suggestions for making it as safe as possible.

Build a “Fed-Up Fund”

How you fill it is your business, and I will tell you it is wickedly hard to do this after you have kids, so I really suggest doing it before.

You should have 3 months of expenses saved up. That gives you time to emotionally recover and find a new job. 6 months is better, but 3 months will probably do.

I can’t tell you the number of women I know who have taken on stressful or unpleasant high-paying jobs to save enough money to have “just walking out” as an option.

Build your team

Make sure you can get ahold of the people you care about without going through your company, your church, or your ex. Make these connections before you do anything drastic, because afterwards, it will feel awkward to reach out to people you are no longer seeing every day.

Find support. It’s emotionally exhausting to be the nail that sticks up. You’re going to need support from your peers, your family, your friends. Make sure Team You is activated and consulted as appropriate before you do anything.

Keep offsite backups

Don’t depend on having crucial information that you are trying to distribute or keep to protect yourself in just one place. Give a copy to a friend, file it with your lawyer. Especially do not count on corporate email to prove your case. They are in charge of the server, not you.

Document everything

I have a friend who worked for a non-profit. She was having real trouble with a person in leadership, and she felt that her job was threatened. When I asked her if she had documentation, she said that she did, but it was all in an account tied to her employment there.

That’s a terrible idea. I am not a lawyer, but in my experience, there’s nothing saying you can’t BCC yourself on emails as long as they don’t have PID or classified information in them. Those cranky emails from your boss? Totally legit to keep for your records, as well as the ones where she told you to do the exact opposite a week ago. If you are whistleblowing about something at your company, or in your volunteer organization, or ANYTHING ELSE, keep your own copy of the documents in question. Keep it secret, keep it safe. You may need it later.

NOTE: There are several circumstances in which you can get sued or prosecuted for removing proprietary information. Talk to a lawyer.

Go into security lockdown

Before you do anything dramatic, pre-emptively go into security lockdown.

Turn on your two-factor authentication, decrease your public social media profile, don’t leave a lot of hooks for people to attack you instead of the problem you’re pointing out.

You may feel silly and paranoid later for doing this, but it’s not going to be something you regret doing.

tl;rt – Too long; read Twitter

I can’t tell you what you should do when you see something going wrong. It’s not as straightforward as George Washington and his mythical cherry tree. I can give you some questions to ask yourself.

Is it true?
Can anything be solved?
Who is against me speaking? Who will be hurt?
Am I willing to pay a price to say this?

Choose. Choose again and again. If it’s true, it will not be less true in the future. You can choose exit then voice, loyalty then exit, exit and voice. But by having noticed something, you are forced to make a decision. Not doing anything is a decision.

People generally make better decisions when they know more about the problem space. That’s why I’m giving this talk

It is a service to tell your company something they don’t know. That doesn’t mean it will always end the way you expect. The stress of keeping secrets is really high. The stress of acting against your beliefs is astronomical. Either you break or your beliefs bend around to encompass horrible things you don’t want to support. At the risk of bringing up morals in a technical talk, you need to be able to live with yourself in the end.

Jobs are transitory, volunteer positions, money, fame, they come and go. But you only have yourself in the end.

Original slides

Pastrybox had a great take on Voice, Loyalty, and Exit.