Praise is a vitamin

I was thinking about how happy I am when I get the kind of praise I need. It doesn’t make me feel smug or complacent, it makes me feel strong and empowered and like what I’m doing matters and is seen. Which is kind of the opposite of burnout. I don’t think you can entirely stave off burnout with praise – it’s systemic and situational, but I think you can certainly help.

I mostly get enough vitamins in my daily diet, so I don’t take a multivitamin. I will take specific stuff if it seems called for – folic acid while pregnant, vitamin D in the dark northern winters, salts when I’m doing a lot of sweating. (Pro-tip: If Gatorade actually tastes good to you, keep drinking it until it returns to its normal grossness).

You would think that most work would also give us what we need to feel rewarded, but some people are just better at metabolizing vitamins from food than other people. Some people can eat all the right stuff and still be desperately short of magnesium, or whatever. Our jobs continue to pay us, our boss is not yelling at us, our coworkers speak to us, surely that’s enough? For some of us, yes. For others, not so much.

For some of us, it’s hard to store praise, just like it’s difficult to store some vitamins. You can take a massive dose, but the body will take what it needs and dump the rest, and you’ll be short again in a couple weeks. Some of us can store praise for a long time, but it’s difficult to replenish, or we can use it all up in a burst.

Some of us walk into work with a chronic deficiency and we’re just going to need the same type of reassurance and praise over and over again, and we can’t help it. We do believe you when you tell us nice things, but it wears out, and we can’t generate it ourselves, anymore than we can generate our own Vitamin C.

Lots of managers realize that we all need praise and attempt to address this with the compliment equivalent of multivitamins. They’ll pat us on the back and say “Good job, I like your work.”, and hope that suffices. It does, for lots of people. But those of us, like me, with specific deficiencies, need more than that. We need something targeted and specific, like a B12 shot, something that can’t be brushed off as lip service or a generality. I like praise about actions that I have taken, especially if they are tied to a goal. So, for example, “Hey, your talk on data privacy really affected people – I heard some guys walking out talking about what they could do to be better.” That’s going to keep me happy about writing talks and giving them for weeks! It’s one of my goals to change people’s thinking and behaviors. On the other hand, “We’re getting a lot of leads from conferences you go to,” is… sales leads are not really my goal? I mean, I’m happy about that, but I don’t know if they’re valuable leads, and I can’t see them, so I’m glad that the company is getting worth from that, but it’s not going to feed me when I sit down to write the next new talk.

As a manager, you’re going to deal with people who have scars from nutritional deficiencies. They may nervously expect that praise always has a dark side, or they may be praise-insecure and never sure that they are going to get it again so they guard it from others. It’s not really your job to diagnose what’s going on, just to figure out what it is that your report is lacking and supply it as best you can, honestly, realistically, and sustainably.I’m working on a new theory where I admit I am anxious and that in the absence of positive feedback, I start getting more and more nervous that there is nothing good to say, and my immanent firing will come soon. People who think they are about to get fired are terrible employees – no creativity, no joy, limited teamwork – for good reason. Rather than end up in that spot, I’d rather say directly, “I need this kind of praise to stay healthy.” Better for me, better for my manager and company.

What kind of praise feeds you? Have you asked for it?PS – Due to my odd childhood, I have a strangely inclusive knowledge of nutritional deficiency diseases. Because I am kind, though, I have not included any of those pictures.

PPS – Did you know that because we use Vitamin C to build collagen, people with severe scurvy can have old healed wounds reopen as the scars dissolve? There’s a metaphor to be had there.

Using Airtable to Manage Conference Submissions

I know, it’s not a very catchy title, but it is descriptive.

A large part of my current job is speaking at conferences and talking about feature flags, systems resiliency, and whatever else I can talk people into. And part of speaking at conferences is applying to lots and lots of conferences. But how do you keep track of it all?

At first I tried to use Google Calendar, but that did’t work. I tried Trello, but there weren’t enough dimensions. I wanted to track these elements:

  • Name
  • Location
  • Start date
  • End date
  • Talks submitted
  • Submitted/accepted/rejected/conflict
  • Speaker tasks
  • Tasks remaining

That’s a lot! I complained about the problem, and Thursday Bram suggested Airtable, as a beautiful mashup of a taskboard and a spreadsheet. Since then, I’ve suggested it to several other developer relations people and I know some of them are using it. I’m now paying for the full version, which gives me the calendar view, and that’s been my killer feature. It really helps me to be realistic about how conferences stack and overlap with each other.

Spreadsheet

Airtable main view

This is the main view. I have it sorted so that conferences that are over or that have not accepted any talks from me are not showing, because I really only need to know about what is coming or may be coming. I’ve grouped it by the Talk Accepted dimension and then the date. At a glance, I can tell what I have coming, and what talk I’m giving (if I remembered to enter it, because I’m sometimes not great at that, as you can see.

Cards

I can drill down into any talk title for a card that has a bunch of information on the talk. Frequently I include the proposal I submitted here, along with information about how far along in the process of creation the talk is, all configured by me. Have I drafted it? Made slides? Practiced it on my own or in front of other people?

Cards Pt. 2

Further down on the talk card, I can see all the conferences I submitted the talk to and whether it was accepted or not. That gives me a good overview of whether a talk is “wearing out” or less likely to be accepted than another kind of talk. It’s useful information.

All of those features are available at the free level, and it’s powerful enough for most people, but did I mention I apply to a lot of conferences? More than there are weeks. You probably don’t need the full version.

Calendar View

Airtable calendar view

This view right here is worth everything I spend on Airtable, and I’m certainly not a power user. But it tells me about conflicts in a way that has been very hard for me to predict from just looking at dates. (If we were all good at predicting conflicts from dates and times, we would not have Outlook Meetings Calendar, is what I’m saying) Now I can tell ahead of time that I can only accept one of those three conferences starting on the 24th, and that allows me to be a more polite speaker. Sometimes it’s possible to look at this and make better arrangements. For example, DevOpsDays Chicago is a great event, but it’s literally the day before I need to be in Dusseldorf. Rather than discombobulating myself or the conferences, I can ask now, months ahead of time, to speak on the first day of DevOpsDays Chicago and toward the end of SRECon. That gives me an error budget for weather/flights/etc. Most conference organizers are lovely about helping me out with these things.

Conclusion

Airtable is a super useful tool for being able to organize data when some parts of it are fixed and some parts change and you need to be able to keep the associations together. There are bigger, more heavyweight databases that can do that, of course, but this is a pretty, friendly, usable implementation of the theory.

If you’re interested in trying it yourself, here is a link to the original workspace I set up: Heidi’s Conferences. Feel free to give it a spin or fork it for your own needs.

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.

The sticker bag

I talked about this a little bit in Lady Speaker Small Talk , but let me expand.

I have a bag of stickers that I take to every conference I go to. This week, I leveled up my game from “gallon ziploc bag of significant antiquity” to “bespoke bag”. It only took me a little while to sew, but I’m super pleased with it, and it uses a fastener I got on my last trip to New York City’s garment district.

A black fabric envelope about the same size as a gallon ziploc bag of obvious age. Black envelope style bag with silver bias edging and a fancy silver buckle fastener.

I made the effort because the sticker bag is important to me — part personal brand, part conversation starter.

Array of various technology stickers More technology stickers spread on a table

I go to over 20 conferences a year, and at each one, I collect vendor and conference stickers, and I talk to the people who give them to me, and then I spread them out on a table at lunch or at the evening party and invite people to come poke through them and take away whatever they want.

This is the most genius spontaneous idea I’ve ever had, because what it gets me is:

  • Low-key, low-pressure opportunities to talk to even shy people
  • A way to talk about different technologies and what people are interested in and looking for
  • A way to gauge what a community of conference attendees is excited about
  • Memorability
  • An extremely keen understanding of the market demands and constraints around stickers

What stickers mean

I am the age to have been a Lisa Frank person growing up. I distinctly remember spending science fair reward money on freakin’ holographic unicorns. It turns out a lot of us have never entirely lost the joy of neat stickers. We put them on our computers, water bottles, notebooks, suitcases, beer fridges, whatever we can get to hold still.

We use them as affiliation identifiers. It may be an obscure sticker to everyone else, but if you care about Debian, you know when you see the Debian sticker on someone else’s gear. You know that they will probably talk to you about Debian. Now imagine leaving that kind of conversational hook twenty times over.

We use them as political statements. An EFF sticker means something, as does a sticker that says “Support your sisters, not just your cis-ters”. Rainbow/pride stickers fly out of my collection, because it’s so important to say “not everyone here is straight”.

Some people have rules about what kind of stickers they’ll use. “I only put stickers on for projects I pay money to.” or “I only use stickers from projects I use.” or “Only funny stickers” or “My laptop has a color theme.”

That all makes sense to me. In many ways, our laptops are a proxy for our faces, especially at conferences. We are hiding behind them physically or metaphorically. When we give a presentation, they peek up over the podium. When we are working in hallways, they identify our status.

Secret Sticker Rules

I think there are some generalizable rules about technology stickers. I feel so strongly about this that when I showed up for my one day in the LaunchDarkly office before I went out into the world, I spent 2 hours talking about stickers, and what I wanted to hand out.

My ideal stickers

  • Small – 2 inches is ideal. Unless you work for a company, you do not want to give them 1/6th of your available laptop space.
  • Tileable – circle stickers are selfish, because you can’t stack them or budge them against any other stickers. I prefer the hex shape, which is relatively standard, especially in open source projects, thanks to RedHat. PS – Heroku, right shape, slightly too big, and it breaks the tiling. I’m judging.
  • Funny – the Chef “sprinkle on some DevOps” stickers are hilarious, cute, and not insulting to anyone. They’re probably optimal. I also really like the Logstash stickers that were a log. With a mustache. And I begged a whole package of the “I ❤️ Pager 💩”. Because people find that hilarious. You don’t have to be funny. Other options are cute, completely straight, or your-logo-but-with-colors.
  • Have your name on them. I cannot tell you how sad it was for Influx Data when they had adorable animals with gems in them, but their name wasn’t anywhere on the stickers, and so I was like, uh, it’s a kiwi bird? From someone? Isn’t it cute? Put your name on the sticker unless you’re, like, Target or Apple.
  • Are not sexist, racist, or otherwise jerkish. I pulled out a bunch of stickers that said “UX-Men”, because while the pun was cute, the exclusion was not. I won’t put out Sumo Logic stickers, because I feel like it’s an ugly caricature. Basho was also right on that line.

I really loved the stickers the LaunchDarkly designer, Melissa came up with. Most of them are hexes, a couple are very small oblongs that fit almost anywhere, and the surprise best-moving sticker is unusually big, a representation of our astronaut, Toggle.

Parents love Toggle, love that Toggle is not gendered, and they take home a sticker for each of their kids.

Other handouts

As I’ve been going to conferences representing a company that isn’t just me, I have figured out some other things that work for me. Feature Management is a new enough market space that people don’t always know what I mean, or want something to take back to their team to explain it. Melissa and I worked together to create a small postcard that has some brand identity on the front and a couple paragraphs on the back explaining our business case. It’s small enough to shove in a pocket or conference bag, and when you get back to your desk, you may read it again to remember why you picked it up.

I also carry business cards, so that people have a way to contact me particularly. I serve as an information conduit between people thinking about how we could solve their problems, and the folks on my team who can definitively answer their questions. So if you say to me “Heidi, I’d love to do feature management, but does it respect semver?” I give you my card and you write me and then I find out yes, we have that coming in this quarter. Yay!

And, of course, I keep a few sets of LaunchDarkly stickers that are not mixed in with the general chaos of The Sticker Bag, so that I can hand them out to people as we are talking about LaunchDarkly in particular. For reasons that mystify me, while Moo has excellent card holders for their tiny cards and business cards, they don’t make ones for the postcards in either size, and looking on Amazon and Etsy was just a journey into despair and disambiguation.

So I expensed some materials and made my own, and as soon as I sort out my authentication with Instructables, I’ll post the process, but look, I made a card holder for all my cards!

Navy leather card holder in clutch size Card wallet interior, with postcards, stickers, and business cards.

The postcard side is gusseted so I can stack a few postcards in it, and the business card holder side can also hold stickers. And the whole thing is sized to fit in my hoodie pocket, because that’s what I’m wearing 95% of the time I’m on a conference floor.

What I Don’t Hand Out

T-shirts. Such a nightmare, because they’re bulky and sizing is variable, and I’m traveling light. If you want a t-shirt, write us and we will ship it to you. 😉

Socks. Because we don’t have any yet, but I continue to hope that we will get socks before the technology sock craze (Started by StitchFix, those cunning geniuses) dies out. I love tech socks. At last count, I have 22 pairs of tech socks, and my current favorite pair is from Sentry.io because they come in a version that has SCREAMING CORAL as the cuff color.

To Sum Up

When interacting with people, it’s nice to give them something tangible, but not burdensome, so they remember you fondly. Also, I’m glad I bought a sewing machine, even though it’s one of the three weeks a year a fat bike would be useful.

Well, that didn’t go like I imagined

The Toggle Talk

As a speaker, there are three things I count on to give a talk:

  • Slides
  • Narrative flow
  • Speaker notes

My dependence on these elements decreases as I give a talk multiple times, but I use the slides to help me remember where I am in the narrative even if I don’t refer to the speaker notes often.

This fall, I designed a new talk and built it in Twine, a game engine for choose-your-own-adventure games. Each slide was actually an HTML page rendered by the game engine, and the narrative was supplied by the audience choosing from several options. This was a radical departure from my usual method, but I’d practiced it, and tuned it, and wrestled with the CSS and I felt pretty confident I could make it work, even though I wouldn’t have speaker notes or a unified narrative through-line.

Because I hadn’t solved the hosting problem yet, I needed to “play” it from my laptop, but that was no problem – I had a USB-C to HDMI adapter. The talk before mine ran long, but I only have technical problems a tiny handful of times in my talks, so I didn’t think I’d need much time to get set up.

I had reckoned without the USB-C/USB-3/HDMI problem, because it had never happened before. I always present from my ipad, and it’s usually a rock-solid toolchain. So I get up there, I’m rushed for time because of the talk before, I’m nervous because it’s the first time I’m giving this talk, and because it’s so “weird”, and…. it failed. The combination of cable/laptop/projector failed so hard that my computer rebooted and came back looking weird, and I had to accept that I might have just bricked my brand-new work laptop, in front of an audience, in a talk that had already technically started.

I had no slides.

I had no notes.

I had no narrative.

I had practiced, but I had not practiced the complete failure scenario, because it had never occurred to me that it could fail this hard.

I still managed to pull a coherent technical talk out and I only ran 10 minutes short, and honestly, it’s one of the accomplishments I’m proudest of in the last year. Literally everything went wrong and I still delivered value.

Afterwards, when I was trying to quietly dump adrenaline, I could only think about how I had failed to achieve any part of my goals. My hands were shaking, my throat was tight, and I felt a little like crying.

That wasn’t how it was supposed to go!

Later, I got to talk to people who had been in the audience, and they asked questions that they could have had if they’d gotten the real talk. That was cheering. I joked that this was the worst this talk could possibly go, because there wasn’t anything left to fail!

Then I got the speaker evaluation cards, and people were universally complimentary about my poise under tough circumstances. It hadn’t felt like poise, it felt like literal flop-sweat, like a drip from my shoulderblades to my waist. But they couldn’t feel my sweat, they could only experience my description of a brand-new talk focused on something that they had to imagine.

The webinar

One of LaunchDarkly’s goals for the year is to nurture and encourage customers to feel comfortable telling their stories, whether on stage or in a blog post. To that end, we are offering some people speaker training. Remembering my fall experiences, I solicited nice people on Twitter to come to a beta of my talk. That would give me a chance to try out the tool, the content, the process, before we offered it as a finished product.

I learned so much! Almost all of it was a little painful.

  • I need to log in early because I’m a panelist, not a host, so we need to coordinate that so I can show my slides to the webinar.
  • I did test my A/V setup!
  • I didn’t realize how unnerving it would be for me to talk to dead air. For all of my teaching/preaching/tech talks, I’ve had an audience. I can make eye contact with them, hear them start to fidget if they are checking out, notice their grins and twinkles and coughs to stay connected to them. But obviously, none of that happens when I’m talking into a headset with the audience on mute.
  • I need to do some work on the content. Not too bad, but I always have to give a talk at least once to live humans to get the suck out.
  • The lack of response makes me so nervous I talk even faster than usual. SLOW DOWN, ME.
  • I have to figure out a better way to wrap up/end the webinar. I didn’t think about how to tie it up neatly, because talks work differently.

So this is all great. When I do the webinar “for reals”, those are all mistakes that I’m not going to need to make because I know where they are.

The meta-lessons

  • It is hard to predict how you’re going to fail, but it is possible to build in a reasonable degree of redundancy.
  • Tests in isolation are not going to catch systemic problems.
  • It is better to degrade what you provide rather than failing entirely.
  • Test with a subset of users so you can predict how your solution will scale.
  • Don’t get so distracted by your failures that you fail to notice surprising data or silver linings.*

* One of the most beautiful night skies I’ve ever seen was on a winter night in the middle of a widespread blackout. I was stomping across the yard to get firewood, and I happened to look up and see the stars without light pollution. A lot of things had gone wrong, but if they hadn’t, I would not have had that moment of starlight bright enough to reflect off the snow, and the milky way like a second snowy stripe in the sky.

Packing, optimizing, and satisficing

I’m off on a two-week trip that happens to be broken by an 18 hour stop at home. (Nodevember, North Bay Python, SpringOne Platform, LaunchDarkly writing sprint). Every couple months, I try to clean out my bags entirely, get rid of the trash that accumulates, make sure that I have room for all the new fidget spinners, that sort of thing. This time I thought I’d share what it is I take along.

In summary, if you are at a conference with me and need Imitrex, Immodium, condoms, period supplies, emergency protein, or stickers, I’m your gal.

Continue reading

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: http://www.heidiwaterhouse.com/2017/05/26/the-death-of-data-signal-2017-edition/

Our tools shape our worldview, or Least-bad Confluence techniques

If you have been in a conference open space with me, you know that I make a terrible yuck face whenever you ask me to talk about working with Confluence. I have yet to work with an instance of Confluence that didn’t make my soul hurt. But it’s not really the technology’s fault if I hate it, is it? Isn’t it about implementation? Aren’t tools essentially neutral?

Yes and no. We talk about opinionated programming languages, but every tool has an opinion about how it should be used, a happy path. For example, the WordPress mobile app is great, and I love it for composing blog posts on the go – that’s what it was made for. But I would find it really irritating as a progress tracker if I tried to use it to replace Trello. Trello thinks in tasks and it’s hard to get it to show you the overall picture of a project. We can go through our whole toolchain like that — each piece of software we build or buy has a way it wants to be used, and although we can hack our way around that, it’s always going to be. more friction than using tools as they were intended.


Problem space

I’ve been to many DevOps Days in the last couple years, and I keep seeing the same pattern of problem.

  1. Documentation exists…somewhere, but no one can find it.
  2. People write documentation and no one can find it.
  3. Documentation is scattered across many locations and no one can find the parts they want.
  4. Standardizing or consolidating the documentation seems impossible because there’s so much of it, in so many places.

This is almost always in a Confluence shop — some people are using other wikis, some people have Word files, but the problem is really recurrent in the Confluence-using places.

Possible solutions

I have some suggestions for how you can make this better in your organization.

  1. Install a better search engine. The one that comes with Confluence is remarkably unhelpful at surfacing current, relevant data. It says it’s searching on relevance, but the returns are difficult to read and frequently so outdated as to be unhelpful.
  2. Break your silos. One of the ways that Confluence is opinionated is that it’s designed to work in silos. Development doesn’t automatically see marketing. Sometimes, this is intentional access control and sometimes it’s just an artifact of thinking in organization charts. Either way, it keeps people from being able to efficiently share information within a company. If you are setting up a wiki or CMS, make it as flat and open as possible. Separate items by task, not job title.
  3. Delete about half of what you have. If you do an analysis, I bet you’ll. find that there is a lot of outdated information. I don’t know what it is about wikis, but they are amazing as graveyards of information that has expired. I think it may be because web pages get refreshed periodically, but it’s been true of every wiki I’ve worked with that there is a bunch of old, wrong data.
  4. Put in analytics. See what people are actually using, and what they’re looking for and not finding. That’s how you know where you should focus your first efforts.
  5. Have one clear purpose for each document: Is it to help tech support answer questions? Is it to document the deployment process to increase pager duty depth? Setting a clear goal for you documentation lets you check everything against that standard.

But!

Of course you can’t implement all of those solutions. Not now and maybe not ever. But you can do some of them whether or not you have buy-in from the rest of the company. Define the purpose of your company and your job and your documentation. Once you know that, you can start working toward it. Next, let the analytics run for a while, and put together a report on them.

When you realize people are trying to search on something that exists and they can’t find it, upgrade your search engine. Once your team is actually using search, you can use the same analytics to strip out low-value or never-used data to make room for more.


What do you think? What tool have you noticed changing your thinking and process? This is one of the reasons I love Monument Valley – while it has predictable rules, it also plays with the dimensions of 2D and 3D space, and it surprises us with optical illusions based on the way we portray dimensional things on a flat screen.

Let’s think about how our viewpoint is constrained by our software, and whether we can spin our point of view.

Retrograde tooling

We've reached a tipping point in technical writing, and we need to deal with it.

The future is not going to involve producing documents, it's going to be producing seamlessly integrated content in and around products, and that means we need to change our expectations around tooling. This is going to hurt, but hopefully in the good way.

When I started writing, I learned FrameMaker. It was amazing. It had 20 years of history even at that point, and you could do anything with it. Equations, printer's crop marks, swapping text blocks in and out automatically, producing print, PDF, and help files from the same file, complete with changing cross-references. Using Frame was as much art and science, and there were key commands that were transmitted through the mailing list, by word of mouth, because they were no longer in the official documentation. It had a learning curve like a brick wall, but once you got through it, you were driving an unstoppable tank that could roll over any problem.

After 15 years, including occasional painful exposures to trying to do professional documentation in Microsoft Word, we got a new, hot product called MadCap Flare. It was like FrameMaker had been reincarnated for the web. It was easier to use, had integrations for localization, CSS, HTML5. It was shiny and beautiful and powerful. I could still do conditional text, referenced text blocks, and single-sourcing.

I haven't used a technical writing tool like that in 18 months, and I think it will happen less and less often.

The rise of Software as a Service and app culture is driving us away from a world of User Guides and Admin Guides and Installation Guides. Instead of CDs with instructions, we expect pop-up help bubbles and interfaces that guide us through what we should be doing. This makes a lot of sense, since we are all experiencing individualized experiences based on our bandwidth, app collisions, needs, and licensing structures. Writing a document that includes all that would be extremely difficult with the old tools, and we don't have the old tools anymore.

We don't have them because without the need to produce Official Documentation, we've reduced and eliminated technical writing departments and jobs. We're moving a lot of that work into User Experience, and we are asking the writers that remain to serve as a clearinghouse for content produced by developers. Instead of a journalism model, where we interviewed developers or were embedded on the team, we are now working as aggregators, taking content from many sources and getting it ready to distribute. Or there just isn't a writer, and publishing is much more ad hoc.

FrameMaker and Madcap Flare cost between $1000 and $2000 per seat license. That's not something you're going to buy for someone who is doing it part time. And it's hard to port data in and out of them, because of all the metatext and compiled information that's attached to them in the tools. It's a database, not a set of flat files. Or more accurately, it's a compiled binary – not the program, the document. So a writer using one of these tools would be a hard gating function on a team's ability to publish their own writing. It would look great, but you'd have a single point of failure.

Instead, we've been moving toward having technical writers use tools that are freely accessible to developers. Markdown that is compiled with readthedocs or readme.io or some other blunt-force tool to create a page with a table of contents and some minimal linking. The advantage of this is that everyone can read, write, and access the docs. The downside, which is mostly only visible to technical writers, is that we have lost enormous richness in treating our documentation as an object-oriented compiled object.

Here are some examples of things that I either can't do or are very difficult:

  • Conditional text – different output text based on flags set on the whole document.
  • White-labeling – configuring my documents so secondary organizations could brand them themselves
  • Smart localization – Doing bulk localization based on common words and phrases, reducing translation time and cost
  • Write once/publish many – having a master document that can produce help, web pages, print, and in-product assistance
  • Context-sensitive help tied to the page the user is on
  • Tables – Markdown, why are you so bad at this?
  • Sophisticated layouts – headers, footers, breadcrumbs, inset images and text blocks
  • Automatic ingestion and formatting of other file formats
  • Includes, referenced text, inserted files – think libraries

That's a lot to lose! Sometimes I feel like writing in Markdown is like making Gutenberg to give up on the printing press and presenting him with and angry goose and a curly sheepskin.

However, it's not going to do me any good to bemoan the lost glories of the tech writing tools Roman Age, because we are in the Dark Ages now, and we just have to move forward to the Enlightenment as soon as we can.

….I was going to make a comparison table for you here in WordPress, but that's not a thing. My point exactly.

Anyway, here's what I think we could start using to regain some of our lost abilities:
CSS – Might be able to help with layouts, HTML5 support, tables, and white-labeling
Feature flags – conditional text, write once/publish many, and ingestion
HTML – (stop laughing. HTML is much more fully featured than Markdown) tables, context-sensitive help, includes
De-duplication – smart localization, includes
Javascript, PHP, etc – ingestion and formatting, menuing, navigation, breadcrumbs

Wow, that's a lot to learn. On the other hand, I heard a talk last week that included a 5 minute list of everything you "needed" to know to become a useful devops engineer, so I guess it's not bad compared to that. It is a pretty intimidating list for people who got into technical writing because they like writing, rather than because they like technology. It's not that writers can't learn tech – obviously we can, because we learned those old tools. It's that there is only the beginning of a community around this new renaissance writing, and no one tool that we can teach juniors.

I fell into tech writing because I took an English literature class with a very avant-garde professor who taught us hand-coded HTML (because 1995). That was the key that opened the door for me. But what key is out there now?

I hope Corilla continues to learn and grow and thrive – they could add in many of these features or already have them.

I hope Read the Docs gets enough funding to hire someone who is a technical writer as well as a coder, because they are missing some significant use cases, but they are also an industry standard.

I hope the OpenAPI standard and Swagger make it more possible and easier to expand their powerful use of code snippets into non-API documentation, because they are coming at the problem a new way and it involves a lot of the hypertextuality I'm looking for.

I hope Confluence realizes that they are setting people up to create unusable wikis because they default to an older, siloed world.

And honestly, I hope SharePoint spontaneously combusts, because that is TERRIBLE.

Why on earth would developers WANT to write documentation?

This week I was at DevOpsDays Minneapolis, which was an amazing, warm, and inclusive event. There were at least three open spaces on documentation, communication, and related problems, and I didn’t propose any of them!

Minneapolis DevOpsDays 2017 logo

The question the devops world keeps asking, over and over again is,

How do I get developers to write anything?

There aren’t a lot of easy answers for this.

The first one is that if you care about developer-produced documentation, you should hire for it. But almost always, the people hiring are not the same as the people feeling the pain of missing documentation, so that may not happen.

The second is that you should hire someone other than the developers to write, if that’s important to you. I’m going to mention that all the times I’ve interviewed at Google, it was to be as an internal systems writer, documenting how things in the company work for other people in the company. Big, smart, companies hire writers for internal documents. But that is a tough budgetary sell.

The third, partial, answer, is that you make it significantly easier for developers to write. You give them forms and templates to fill in instead of expecting them to invent documentation theory. You specifically allocate writing time that can’t be budged for “one more tweak to the feature”.

Here’s the key problem though:

No developer has ever been fired for lack of documentation.

No developer I know of has gotten a bonus for documentation.

There is no stick. There is no carrot. There are a lot of competing demands on a developer’s time. Why on earth would they go do something that is not in their core competency just because you want it?

My instinctive response, whenever my kids want something, is to say, “It’s good to want things.” I think that is the instinctive response of most developers who are asked to do extra work. It’s not malicious, it’s just true. There is no reason they should do it – they won’t lose their jobs, the way they might if they prioritized writing over code. They won’t derive any benefit except the long-term and intangible one of being asked fewer questions. If they like being the source of knowledge, they’d be giving that away. If they like coding, you’re asking them to do something other than what they want. There is no upside.

So knowing that, how can we encourage developers to write documentation that we need?

First, reward it. Give people prizes for writing docs, or for throwing away or revising old docs. This needs to be something outside their usual compensation structure. Gift cards, time off, merit badges, whatever would be meaningful to that person. Ask them. They know what rewards them, because they use it to reward themselves.

A variety of rewards

Second, require it. I don’t mean “You have to write some docs or I will, uh, be disappointed in you.” I mean “The presence of documentation is a quality gate and you cannot release without it.” I mean “QA is using your docs as the test story.”.

Companies are never altruistic, humans are never purely motivated. We need to accept this and stop expecting people to do extra work because it’s the right thing to do, and start making the work not-extra, and the reward tangible.