A small succulent plant with the San Francisco skyline in the background

Crosspost: The Recompiler Magazine, Issue 8: Build Your Interviewing Strategy

I’m a huge fan of The Recompiler, and not just because they sometimes publish my work. I support anyone who spends the time and effort to publish articles that are useful, thoughtful, and frequently action-oriented.

Carol Smith (of OSI board fame) and I put together a workshop for people who are doing technical interviews for the first time. We called it “The Hardest Part of Tech(nical Interviewing) Is People”. We’ve given it a couple times, and we’re hoping to do a recorded version. This article is part of what we talk about in the workshop – how to look over your past experiences, even if they weren’t in technology, and make them relevant and applicable. We hope this helps you!

Build Your Interviewing Strategy

And in conclusion, support your local publications!

The Recompiler Magazine

Screaming in the Cloud with Corey Quinn

Corey Quinn, slasher of AWS bills and frequent conference speaker, had me as the first guest on his brand-new podcast, Screaming in the Cloud. We had a great time talking about feature flags, the all-iPad conference setup, testing in production, and how I feel about technical documentation.

And if you’re like me and don’t always have time to listen to podcasts, there’s also a transcript!

(This is the third time I’ve been asked to help kick off a podcast. Feel free to ask me for your own podcast!)

Guest post: UX Booth

I wrote a 2018 User Experience Prediction at UX Booth. Amy Grace Wells asked me what I thought was going to be a leading theme in UX in the next year, and I said, “better accessibility”. I think that’s both a serious prediction and a hope, because there is never enough accessibility, but I also think we are getting better.

So many things that are designed for accessibility, but that we don’t always understand that way when they happen, and frequently we mock them as lazy or luxurious. Backup cameras on cars seem silly – why not just turn around? Until you physically can’t turn around, and then you realize how much they matter. Pre-chopped vegetables, electric can-openers, and velcro shoes seem laughable – unless you’ve ever been unable to hold something in both hands at once. In the same way, building web and mobile apps to respond to a variety of command styles may not occur to us if our fingers are nimble or our voices clear, but will matter immensely to people who are not in that category.

Since before I was employed at LaunchDarkly, I’ve been fascinated by the ability that feature flags offer designers to customize user experience. We haven’t had a good test case yet that I know of, but it will come, and I’m looking forward to it.

Peeled oranges in plastic containers

Pre-peeled oranges for accessibility

Post on Opensource.com: How to nail a tech writer job inteview

I was excited to write another post for opensource.com:

How to nail a tech writer job interview

It’s an extension of a twitter rant I went on a bit ago, about how important it is to know certain things about interviewing as a technical writer, but no one is teaching them, from what I can tell.

  • What kind of samples should you offer?
  • What is ethical to use as a sample?
  • What is a reasonable (and unreasonable) writing test?
  • How do you talk about team projects or work for hire?

I’m already in discussions with the team about a follow-up, based on my New Sheriff In Town talk. That one will cover how to walk into a new position and figure out what to write first.

If you’re interested in more content on interviewing, Carol Smith and I are putting the finishing touches on a workshop about all the not-code parts of a technical interview. You’ll be able to read more about that in The Recompiler soon, and of course, I’ll post about it here.

 

Response to: Modern Technical Writing, by Andrew Etter

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

Etter says,

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

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

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

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

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

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

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

You = Top 5%–8%

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

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

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

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

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

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

Guest post: SysAdvent!

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

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

SysAdvent Logo

SysAdvent Logo

Many hands make a messy wiki

In October, I attended HydraConnect. To my relief, it was not a networking event for evil comic book characters, but rather an in-depth conference for people running the Hydra software, which is used in higher education (and other library-like places) to organize digital collections.

When I walked in the first day, I didn’t even know that much. I’d been contracted to attend the unconference days and add a technical writing perspective to a distributed open source project. I wasn’t sure if I would actually add value, but it seemed worth the experiment, and I learned and taught a bunch of things, which I will summarize here.

Your documentation needs a lifespan

There are two problems in software documentation:

  • Getting anyone to do it.
  • Getting rid of it.

This is especially true in distributed open-source projects because there are many people contributing, but seldom a firm hand disposing. My proposal is that you PROGRAMATICALLY make your wiki pages expire after a year to trim down your documentation cruft and help keep all your docs accurate.

Scenario: You sit down and check your dashboard. Three notices appear for pages expiring this week. You click on the link to the first one. It is a workaround for a bug that has been patched. Do nothing. This data should die. The second one is a valuable tutorial that you know people still use. You check to make sure it still looks accurate, and click the Renew button. Safe for another year. The third link leads to a requirements page that should get updated now that some of the software mentioned is too old to be supported. You edit the page to be accurate and click Renew.

I came up with this idea because of some work I’d done years ago with people interested in sunsetting personally identifiable data. This is not quite the same as Right to Be Forgotten, it’s more that just because we can store an effectively infinite amount of data doesn’t mean we should.

Do you think there are actually 36 million people working for the government? No, but anyone who has worked for the goverment in the age of data had their information collected and NEVER PURGED. A huge part of that vulnerability is because our data never expires.

Data should have a lifespan. Technical data should get reviewed every year. Credit data should roll off after seven years. Your entire childhood posting history should get wiped when you turn 18. If we were more mindful about this, we’d have cleaner docs AND fewer horrifying data breaches.

Your documentation should get treated like code

This is not a new concept, but it’s especially useful for distributed teams.

  • Keep your docs in a repository
  • Write bugs against them
  • Include them as part of features
  • Write tests against your docs. If a novice user can’t follow your directions to do a task, you are not done. You can also use your docs as a test. If you follow the directions and the thing doesn’t install, you need to find out where the problem is.

Good examples are as important as good explanation

I could spend 300 words explaining to you how I like my peanut butter and jelly sandwiches made (toast, raspberry jam), or I could hand you my sandwich and let you see for yourself how it works.

Many people need that concrete example to understand what is possible for them to accomplish. Some of my current favorite documentation are the Swagger API docs. They are not very wordy at all, super minimal, but you get a sample site that works, and then you can play with it, and the documentation is all baked into that. I can see how it’s supposed to work, instead of following a process and hoping I get it right enough to work.

Search is how new users learn

When you get stuck on a new problem, especially if you’re not sitting next to someone who can answer your question, what do you do? Most developers and IT people I’ve talked to Google it, almost as a spinal reflex. If you are not doing internal analytics and designing internal SEO around that, then Stack Overflow is doing a better job supporting your product than you are. That’s not catastrophic, but it’s not great, either.

Set up analytics on your wiki, your web page, your help, wherever you are storing your documents, and start watching the search terms people are using. If your documents don’t answer the questions, write more. If the queries are using the wrong language, add better tags and keywords to your documents so they’re findable. I’m really glad someone wrote that, but it is a tiny bit worse than useless if no one ever finds it.

Drawing the elephant is better than explaining one piece at a time

Do you know the story about the six blind men trying to explain an elephant? One gets hold of the ear, and says, “I percieve that an elephant is very like a fan.” Another finds the elephant’s flank and deems it wall-like. Each person has a different experience of the elephant and even talking to each other, they can’t conceptualize “elephant”. Is your documentation like those people talking to each other? Has anyone provided a picture or description of the elephant? High-level conceptual topics are both difficult to write and technically complicated. You have to understand both the audience and the product. But without that description, you just have a bunch of disparate tasks.

Which leads me to my next point…

Context increases compliance

Knowing why I’m doing something makes me much better about doing it. I don’t let strangers poke me with needles, but I do get my flu shot, because I have enough context to know that it is the lesser evil.

If you’re asking people, especially volunteers, to do work, you need to be able to explain how their effort is going to be a benefit to the organization. It doesn’t need to be An Epic Explanation, just a little something to guide people. “Let’s get these chairs stacked out of the way for the karate class coming in.” is much more contextual that “We need these chairs in stacks of four.” Be sure you are providing acessible context for the product and the project.

Summary

Distributed teams that are not specialist writers can still create documentation, but they need to get rid of old docs and they need to have a clear vision of what they are doing and why.

Postscript

I really enjoyed the experience of the conference. Badges with pronouns! Other women, of all ages. But I also enjoyed being a technical writer at people. I’d like to do that again, for other projects that can’t afford a writer but do need a writer perspective

(crossposted and updated from LinkedIn, thanks to Sumana for the nudge)

The Seven Righteous Fights: Overview

This is a series derived from my popular talk “The Seven Righteous Fights”. It’s not an exact transcript, but I think having a written form to refer people to greatly increases accessibility and gives me room to expand my thoughts in a way that is not compatible with speaking.

There are seven fights that I have over and over again, whenever I start at a company. The more software you build, the more it’s obvious that there are seven fights that it will alway pay to have.

My background as a writer means that I am trained to perform a lot of analysis and synthesis. If I don’t understand the product from value proposition through implementation, it means that I am not the writer I want to be. I call it being a full-stack writer. The problem with having all this training in analysis is that you can’t exactly turn it off. I don’t stay in my lane well, I can’t notice problem that only fall into the narrow category of “documentation”. They’re all documentation problems, they’re all software problems, they’re all design and usability problems.

I’ve worked for roughly 15 companies and my conclusion is that when we create something new, we tend to make similar mistakes every time. This is probably because we all tend to settle in a comfortable stage of product development. Some people prefer mature products, some people like the very beginning and hate the mature product maintenance. But that preference means we don’t understand pain points that happen at other stages.

I’m an early-stage person. I love writing the first version of documentation. I love that green field and that new product smell. But I have done enough mid-stage stuff to know the emergent consequences of early-stage decisions. And like everything you’ve ever read about compound interest, early mistakes compound until they are enormous.

I was working with a startup that was pushing super hard to get their product ready to demo at a big industry conference. They were stripping off every feature they didn’t absolutely need in order to make sure they made their deadline, and I was helping. We made the deadline, there was documentation, and they got a POC contract… with a company in Brazil.

In the process of rushing to get ready, we had stripped out all of the plans to make the interface labels link to a file we could localize, and we had hand-coded all the labels. Now instead of handing off a single file to be translated into Portuguese (and having standard labels that could have been done with Google Translate, in a pinch), we either had to branch and hand-code Portuguese labels or spend twice as long digging into the original code and fixing what we had hacked. I’d love to tell you we decided to do it right, but you all know too much about software to believe that happened, don’t you?

The compounded interest from not using a best practice of referred labels when we built the user interface cost us five days of developer time to fix the wrong way, and two weeks to fix and rebuild the right way. That’s a relatively common example of things people skip and pay for later.

Leaving important considerations “until we get a working prototype” means that it’s going to be harder and more expensive to retrofit. Having these fights early prevents you from doing the software equivalent of poking chocolate chips into already-baked cookies.

cookies

Next: The Seven Righteous Fights: Localization

If you’d prefer to watch the talk as I delivered it:
Shortest recorded version: At The Lead Developer 2016

Longest recorded version: At SpringOne Platform 2016