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.

BIG CONCEPTS small docs. User documentation is a failure of user interface. Faster and cheaper than making your developer write it. Elegant writing saves money. Paid by the anti-word.

Why are there no documentation bootcamps or schools?

Sarah Mei and Sarah Fox and some other people and I were talking on Twitter about code school graduates, and how they frequently do really well at mid-level positions because they have communication skills from their previous careers.

We all agree that teaching someone to write well enough to be a Professional Technical Writer is more than you could cover in a six-week intensive, probably. Depending on where they start. I could absolutely turn a motivated journalist into an entry-level tech writer in 6 weeks. They’re 3/4 of the way there already. But most people would need to learn the following from scratch (in no particular order):

  • Audience analysis
  • Task-based writing
  • Procedural writing
  • User story writing
  • Error writing
  • Bug writing
  • Conceptual writing
  • Diagrams, illustrations, and screen captures
  • Rudimentary tools use
  • Sentence construction
  • Bullet point use
  • Theory of simplified English
  • Accepting editorial feedback
  • Accepting technical feedback
  • Elements of information architecture and presentation
  • Elements of usability and accessibility
  • Style guide use

Even if you’re coming out of a liberal arts/literary background, half of that list is something you may never have heard of. You can construct a great sentence, and you know how to use a semicolon, but your experience to date has rewarded you for things that don’t matter at all in technical writing. You’ve gotten good grades for making persuasive arguments or writing pithy literature reviews, but no one in my English Lit classes ever told me that I was addressing the wrong audience or designing my headings badly.

So that’s a daunting list of things to try to cram to get people into what is, let’s face it, a less glamorous profession than Code Warrior. I happen to think it’s the best and most influential place to be in a development team, but that’s not what the pay scales say.

That said

That said, I think I could do a LOT with teaching code school students and other developers some really basic writing skills. I tried this out at a Workshop at Write the Docs this year, and it went pretty well. I’d love to present it elsewhere. I’m putting the outline below the cut, if you’re interested.

Give me your developers for a day, and I’ll teach them to write a well-constructed error code and a readable bug report and a coherent status email. Give me two days and I’ll teach them about audience and analytics and deletion.

I want to do this for code schools, so we can catch people when they are frantically learning, so they will remember to look it up later. I want to do this for open source projects, because it is so hard to find or hire a technical writer. I want to do this for conferences where junior developers are looking to elevate their game. I have been traveling around to developer conferences for several years now, trying to distill everything I know from 20 years of my career into something that has value for coders, and I am convinced it has value.

Continue reading

Creative destruction

I was making a joke about the fact that I accidentally have two profiles for Open Source Bridge – one is with pink hair, and one with brown hair. Obviously, one of them is the mirror universe me. Probably the one with brown hair. No one with pink hair could be sinister, right?


I said that my mirror universe self would obviously specialize in creative destruction, instead of speed-building documentation sets from nothing. But in truth, I do both.

Any sufficiently complicated documentation set is indistinguishable from a pile of cruft.

Creative destruction is related to deleting, but is not the same. Creative destruction is less trashing things by category, and more like letting a herd of goats loose to clear a hillside covered in Himalayan blackberry. The goats are a lot more discriminating and not as destructive as a flamethrower, but they are omnivorous enough that your wild roses may also get eaten with your blackberry brambles. Creative destruction lets you take a cleared space and plant something new in it, without having to work around what has grown up over time.

This is the part of the konmari method that I identified with most. Put everything of a category together, look at it, and decide what it is that you want to keep. It's really difficult to make distributed decisions because it requires holding all the objects of that type in working memory, and our working memory, as literate humans, is just not that good. Play to your strengths, which in this case means "make it easier to be bold about deletion/destruction".

When I walk into an organization with existing documentation, I like to do a gap analysis: What traditional docs sections might they be missing? What things do I wish I knew as someone new to the product? Does the documentation cover every step of the product, from pre-installation to removal? Can people make good business decisions based on these documents?

A documentation destructionist looks to see what we can carefully, mindfully burn to the ground. Is it old? Is it about something we don't support? Is it a path we didn't follow? Archive it, delete it, and move on. You don't want to leave old versions of anything around if it will confuse the issue when someone is trying to use your tool.

Clearing a swath of ground makes it possible to see the daylight between the trees, give your good docs a bit of breathing space, plant new things that you want for the future or the present. New ideas grow best with some sunshine and elbow room, and even if you have infinite storage space for documentation, no one has infinite attention to read or maintain it.

Happy Tuesday! What can you destroy today? What would your documentation set be better without? What is out there bothering you ever time you go past it? Go get rid of it!