Stickers, A Love Story

When I was in elementary school, I won a science fair, and travelled to the far-off land of Moscow, Idaho for the state competition. While there, I spent some of my food money on the most magical sticker ever. It was a gleaming metallic unicorn with rainbow colored mane and tail. It brought me joy every time I saw it, and reminded me how hard I had worked and how exciting it was to travel to show off my experiment.

When laptop stickers started appearing, I felt the same way about them, a bit. They are reminders to us of things that we have done or accomplished, and they are signals to others about what we care about.

When I started at LaunchDarkly, I had one day in the office, and the thing I spent the most time on was talking with our (genius) designer Melissa about stickers and what we should do with them. We have just done a refresh of our Toggle character, and now they look like this:

So cute! So space-tastic!

In the last year, I even built a sticker lightning talk to address why I care so much about this, and I’m always charmed to look out at the audience and see the smiles and nods as people feel seen and understood.

Why do we care?

Why do/should tech companies and other companies care? What makes it worthwhile for me to carry around a few pounds of stickers and experience the delights of confusing the TSA?

In-group markers and identity

It is so important to people to be represented and known for themselves. Whenever I have stickers that relate to pronouns or sexual orientation, people make a delighted face and pick them up and hold them close.

And it’s not just the things about personality – a Go programmer is happy to find a gopher. Someone who does DevSecOps loves to find a sticker that describes their job.

I can spot the networking people, for example. They are the ones who think the Fastly 418 (I’m a teapot) the Target 127.0.0.1 Sweet 127.0.0.1 sticker are hilarious. Because they are jokes that relate to HTTP return codes and IP addresses.

Then we have another layer of delight when we can put them on a laptop and be seen and found by others in our in-group. If I have a sticker from a conference you’ve been to, we can talk about our experiences. If you see a sticker that indicates we share something, it’s much less intimidating to start a conversation.

For example, if you see this sticker, there’s a pretty good chance that the person has actually met me.

Similarly, if you have a sticker showing in a video or on your laptop, it could be a lead to something that people want to know about. I get a lot of questions about my OSMI stickers, which is about Open Source Mental Illness.

Branding, I guess

The exposure you get from a sticker is a small increment, but small increments add up. They can add up pretty quickly if your sticker is a prompt for someone to act as an advocate when they are asked about the sticker.

Matt (Brender) Broberg did a talk that included an analysis of the return on investment of stickers.

(the last bit is obscured, but it says “Sticker ROI is 5x to 76x”, I think.

People also have sentiment around stickers, in the technical marketing sense. Cute stickers make people feel like your product is fun or delightful to use. High-quality stickers make people feel like you have a high-quality product. Racist or sexist stickers? You’re alienating a lot of people silently.

Even people who don’t know what npm is will take npm stickers because they are SO DARN CUTE.

Surveying

One of the interesting parts of carrying my sticker bag around is that I can get a sense of what technologies are important to a community. It’s not always a 1-1 relationship with the technologies you would expect. Sometimes it is. Either way, I can see the level of interest around a company or technology.

For example, I can tell you that the Kubernetes project is interesting and popular and has a good visual brand and is not doing enough to meet the market demand for their stickers. PHP and Drupal crossover, and that’s not surprising, but so do Verizon and Elastic. One conference may have people who don’t recognize a Chef sticker, and another might wipe out everything I have that relates to automation. I can tell from the stickers that Target developers take that they build a lot of internal tools instead of buying them. It’s interesting!

Developer honeypot

It’s not true that developers are universally shy and anti-social. Some of them are, some of them aren’t. What is true is that it’s hard for a lot of us to strike up conversations with strangers. When I spread out my stickers and invite people to browse and take them, it gives both of us a way to talk about technology in a way that is low-key, not intimidating, and doesn’t even require eye contact. We have time to talk or not talk as we wish.

Design patterns and anti-patterns

I’ve been carrying around The Sticker Bag for about three years now, and in that time I’ve spent a lot of time thinking about what makes a sticker attractive to someone. Some of it is identity and branding, but those feelings can be enhanced or reduced by the design and form-factor of the sticker.

Size

Huge stickers are a mistake. I am almost never excited enough about about your product to dedicate 1/6th of my laptop space to it. I think 2 inches is about ideal – big enough to see and have impact, and small enough to fit in around other things.

Here’s what a set of huge stickers looks like:

But wait! You don’t have to think about it, because, my friends, there is a standard! Visit sticker.how to read it. Interoperability is not just for software and hardware anymore.

Shape

I favor the standard hexagon, because the tiling looks really awesome, but I am not against die-cut stickers that have unique shapes. Hexagon stickers started as an “open source thing”, but have utility for everyone who wants to work together for maximizing laptop space.

I have previously questioned round stickers, because they are not an efficient way to use space, but I think they’re ok as long as they’re smallish. Big circles somehow seem even bigger than big rectangles.

My laptop has a combination of sticker styles, but I don’t put anything on there if I don’t know the people or use the product.

You can see how the Fastly 418 sticker is round, but fits ok with others, and the Spoonflower round sticker is too big to fit harmoniously.

Utility

If you like it, you should put your name on it. Visual branding is hard to do, but it doesn’t do you any good to print awesome-looking, high-quality stickers if no one can tell who the sticker represents.

For example, this sticker was adorable, but for the first year it was out, you couldn’t tell it was from InfluxDB.

The next run of stickers had their name on it, thankfully!

Not for everyone

Not everyone uses tabs, or spaces, or emacs, or vim. Not everyone wants to put stickers on their laptop. They find it cluttery or distracting or unprofessional. That’s fine. There are all sorts of people in the world. Don’t be judgy.

However! Some people would like to be able to represent themselves with stickers, but can’t, because they have a work laptop that they aren’t supposed to stick stuff on. In those cases, consider these sticker hacks:

Sticker hacks

  • Put a lightweight case on your laptop and either put the stickers on the outside, or leave them on their backing and put them UNDER the case. I do this with a bright pink case from Speck.
  • Get one of those vinyl laptop skins that goes on your computer, and then put the stickers on that. I heard of one guy who got a skin made of the stickers that he had on the previous computer, and then put even more stickers on top of that. Truly next level.
  • Don’t put them on your computer! Other destinations I have heard about include: notebooks, water bottles, white boards, and beer fridges.

Resources

  • http://hexb.in/sticker.html
  • https://www.redbubble.com/shop/stickers
  • https://stickerapp.com/materials/holographic
  • https://www.moo.com/us/products/stickers-range.html
  • https://www.etsy.com/shop/DecalSpecialtiesBJ?ref=l2-shopheader-name&section_id=18018884

Conclusion

Stickers may seem like child’s play to some folks, but it’s an interesting insight in to the cultures, self-representation, and identity of people we’re around. And it’s not just technology – miners and construction workers sticker their hardhats. Musicians sticker their instrument cases. If we have a flat surface, a lot of us feel like adorning it is a satisfying activity.

Delight for less than a dollar? Seems like a great deal.

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.

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/

New job title: Developer Advocate

I've had a lot of job titles in my career:

  • Technical Writing Intern
  • Queen of Documentation (It was 2000, OK?)
  • Technical Writer I, II, III
  • Technical Communicator
  • Senior Technical Writer
  • Technical Writing Consultant
  • Documentation Architect
  • Documentation Mercenary

You might notice a theme there. I've been a technical writer for a lot of different companies, because that's been my career, my expertise, and my passion. I want to take everything that's great about technology and make it easier to use, more transparent, more thoughtful, more humane.

Lately, I've been having trouble describing what I am doing in terms of writing alone. Two job interviews in a row, my interviewer stopped asking me questions about my qualifications so they could take notes on my ideas for their product. My conference talks are sort of nominally about writing, but actually about patterns I'm noticing in the world and in technology. I love writing, and I'm never going to give it up, but it's also…not quite a good fit anymore.

Through the power of All-Women-In-Tech-Are-Connected, I got an interview for a Developer Advocate position. I would never have applied for this position on my own – it's so far beyond what I think of as my skill set. But in the discussions and interviews, I really came to believe it was not just a company I could work for happily, and a product that I think is useful and not toxic, but a position that lets me get out there and do the kind of thinking and helping and problem-solving that I love.

Photo credit: Women of Color in Tech Chat

Developer Advocate is a super broad range of positions, actually, but our interpretation of it is basically me continuing to do all the things I'm doing now: conference speaking, blogging, listening, and noticing. It's just that now I'll be doing all that and getting paid for it, instead of using it as a loss leader for my consulting. I get to go out in the world, find out where developers and users need help, and figure out how to make it happen for them. We're seriously at "pinch me, I must be dreaming" levels of exciting here. I even get to keep writing a little, although I may have reached my personal career goal: not writing the release notes.

Yes, I'm being deliberately coy about my new employer. That deserves its own post. I'll just say that I think we're going to get along well, they say I get to continue to be a pink-haired weirdo, and I will feel proud of the product.

I honestly feel like changing my job title is like the day you get new shoes and you realize you'd outgrown the old ones without noticing.

Oh! This is so comfy.

Guest Post on OpenSource.com

I was supposed to be at SeaGL this weekend for an awesome conference with the opensource world. Sadly, I fell in the garage and dislocated my shoulder, so I can’t attend. On the bright side, the post I wrote to promote my talk at the conference is available!

Four Steps to Better Documentation

In it, I talk about a few simple steps to making sure you are writing the documentation that people need, and making it as relevant and accurate as possible.

Enjoy!

Becoming a welcoming open source project, Mentoring Branch

Cate Huston (@catehstn) asked what we could do that would get us from “open source” on a project to “welcoming source”.  Codes of conduct, good newbie issues and good onboarding were her initial suggestions, and I said that a good project would also have a really clear goal, because one of my consistent frustrations with trying to start a project is not understanding what the end goal is and how my contribution furthers that goal.

Then Cate got distracted by “jet skiing” in “Suva” (a likely story), and Mike P (@snowcrashmike) and I went down a rabbit hole about mentoring.

Read the context on Storify

Mike said that senior mentoring was also important, and I agreed, but I thought that was too vague. As I see it, there are four kinds of mentoring on a project.

  1. Mentoring on the project itself — architecture decisions, goals, dead ends that we rejected. This should not be mentoring, this should be DOCUMENTATION. (You knew I was going to say that.)
  2. Mentoring in the art and practice of contributing to any project — interpersonal politics, how not to show fear in the face of code repositories, how to figure out who knows where the bodies are buried.
  3. Mentoring in a specific skill or language that is used on the project.
  4. Career mentoring, which is a catch-all for everything from “how to report bad behavior” to “don’t show up to interviews in a shirt with holes” to “plotting your ascent to the corner office”. (Hah. Pretty sure OSS projects are not rife with corner offices.)

I asked Mike which of those he meant, and we agreed that the ideal mentor would be one who could do all of that. Full-stack mentoring, as it were.

But just like full-stack developers are pretty rare, so are full-stack mentors. Asking someone to have that high level of competence on top of asking them to have a product vision, a genius for distributed management, and a competence at coding just seems like too much.

The best solution would be for people who are already in the project to do some thoughtful discernment about what kinds of mentoring they are good at. For example, I can’t code, and my design sense is marginal, but I can write a pretty mean sentence, walk someone through writing a conference talk, and my problem analysis skills are pretty great. So you shouldn’t really have me do pair programming or mentor by teaching a coding language. You should have me mentor someone on how to come across like less of a jerk on mailing lists. I should be mentoring people on how to write bug reports. I can toss code questions over the wall to someone who understands the code base.

The problem is that of course there are not enough mentors. There are not enough anyones, in open source. That’s just the nature of the beast. So when we say that newbies need mentoring, it’s true, but it puts enormous, unreasonable pressure on the very core maintainers we are trying to prevent from burning out.

Asking someone to repeatedly perform something that is not just outside their skill set, but outside their interest is asking them to do a lot more work than asking them to do something they are strong at and pleased by doing. We all need to develop our growing edges, but I feel like that’s not what this is. Instead, it’s an accidental burnout accelerator, because the people who care most about mentoring are the ones who are going to overextend themselves trying to be everything to everyone.

Let’s not burn out our best mentors.

Instead, here is my suggestion for when a project decides to include new contributors:

  • Document the decisions that you’ve made about where you’re going and where you’re avoiding.
  • Be clear about your goals for the project.
  • Establish not just a code of conduct, but a standard of communication that the project tends toward. Lots of smilies? Bullet points? Simplified English? Bilingual postings? Whatever it is, make sure it’s something the core maintainers are willing and able to do all the time.
  • Mark newbie-friendly bugs, features, and doc requests. Try to attach a mentor to the bug/feature/doc. That way, the load gets passed around, and new people get to work with a lot of team members.
  • When a new person asks for mentoring or seems stuck, ask them what kind of help they’re looking for. They may not know, but they can usually tell if it’s a code problem or a people problem.

Tl;dr: Treat mentoring more like a microservice and less like a monolith.

The Seven Righteous Fights: Security

This is the second fight in my series The Seven Righteous Fights. For an introduction, see The Seven Righteous Fights: Overview.

Contrary to what you may have heard, the internet is not actually a series of tubes connected by guys in ski masks. There are bad actors out there, but your product probably won’t attract them right away.

But there will come a time where you have to send out a really embarrassing email to your clients because your waffle-buddies app has been breached and everyone’s syrup preferences have been posted to a pastebin somewhere.

Waffle and syrup

Syrup and waffle in gorgeous light.

It’s expensive in terms of reputation and in terms of productivity, because everything has to stop while you solve the problem.

Security is probably the place where it would be easiest to over-optimize your product without a lot of benefit, because it takes a lot of experience to do security correctly, and that experience does not come cheaply. It would be ridiculous to do a full security audit on an app that doesn’t handle money or personal identification before it is even out of beta.

That said, I think you can think MORE securely than the next person.

How can I be more secure?

  1.  Understand IN YOUR HEART the differences between authorization, authentication, and security. Being confused about it makes you more likely to build something with a serious flaw.
  2. Leave yourself room to perform encryption. It’s probably never a bad idea to start from HTTPS (on ALL the pages). It’s not going to hurt you to use SSL, even between your own services.
  3. Understand what kind of data needs to be protected, and what people can figure out from “innocuous metadata”. Every piece of data you collect increases the threat surface for you and your user.

    HIPAA and other protective agreements shelter obvious things like your social security number, but also less obvious things, like your birth year if you’re over 90. That’s because it is shockingly easy to figure out who someone is with enough bits of “meaningless” data.

Keep less stuff

Plan to delete users and delete data. Even if you flip a bit that disables logins, if you’re keeping the data, you’re the problem.

We grow and change. Eventually we end up dragging a lifetime of data, like Marley’s chains in A Christmas Carol. They are the chains we forged in life, and they never go away.

I want data jubilee.

Don’t reinvent the wheel

Use someone else’s auth* engine. You don’t have to reinvent the wheel, and you probably shouldn’t. This is especially true if you are in a social space or an enterprise space. The IT people installing your system would really rather you just used Active Directory or SAML or OpenID (but really AD) instead of lovingly hand-crafting your own.

Stop saying that word!

(the word is “secure”)

Imagine that a pack of rabid lawyers are waiting to gnaw on you anytime you claim something false. False things can include “we secure your data”.

Conclusion

You don’t have to build something entirely secure now – that’s prohibitively expensive. But do leave yourself the hooks and plans to add security before you have a major incident.


This blog post is part 2 of my Seven Fights series. You can hear me give this talk at The Lead Developer in London next week (June 22-24) or at SpringOne Platform (August 1-4) or Abstractions (August 18-20).

The Seven Righteous Fights: Localization

This is the first fight in my series The Seven Righteous Fights. For an introduction, see The Seven Righteous Fights: Overview.

Are you ever planning on selling this to someone in another country? Or someone who doesn’t speak your company’s primary language?

I’ll tell you right now: Yes, you are.

There’s a big wide world out there, full of people who don’t speak American-flavored English. If you want to reach them and get their money, you’re going to need to speak to them in their language.

Unless you are working for 18F, everyone has the potential to sell their software overseas. Maybe not this release. Maybe not next release. But soon, and you had better plan for it. Hire a localization consultant for a couple days at the beginning of your project and ask them what they wish people would think of in advance. These are the ones I know of:

  • All labels referenced from a list.
  • No words besides the company name embedded in logos.
  • Extended character support baked in.

Hard-coded labels are going to make it very expensive to localize your user interface. Instead of a “normally expensive” translator to look at your labels file, you’ll need to find someone who can use your interface framework, and you will need to do that for every language you want to use. At this point, most people do the work of pulling the labels into a file for reference, but wouldn’t it be great to save that step?

If you have words in your logo, even things like “Professional” or “Edition”, that should get localized along with everything else. That means redrawing/re-rendering the logo for each language, and burning a bunch of artist time.

Extended character support is important so that you can render all the languages you’re going to use, but it is vital that everyone be able to enter their name, the way they spell it. It is extremely alienating to not be able to identify yourself accurately. Don’t make your users feel like you don’t respect their identity at the very beginning of your relationship.

Be careful of:

  • Explanatory videos
  • Humor
  • Fixed-width elements

Videos provide a powerful way to deliver tutorials on a complicated interface. However, even a user who could translate their way through written instructions may have trouble with the speed of video narration.

Humor translates very strangely. It’s very culturally-based and dependent on things like tone, register, and word choice, things that vary with language and culture. A very good (expensive) translator could translate humor for you, but it’s probably best to leave it alone.

Fixed-width interface elements are going to make you cry when you localize. If you want to see why, take a line of English and use Google Translate to take it to German.

English

German

File Datei
Settings Einstellungen
Edit Bearbeiten
History Geschichte
Log in Einloggen

Different languages take up different amounts of space!

If you use a few best practices while you are coding up your initial product, you will save yourself thousands and thousands of dollars when you go to release internationally. Localization estimation is complicated, but in this English to German translation example, the lowest price I found was 12 cents a word, and the fastest an average translator can work is about 2000 words a day. If you could translate 200 interface words in one referenced file, or 2000 repeated and hard-coded words across dozens of pages, which would you rather pay for?


This blog post is part 1 of my Seven Fights series. You can hear me give this talk at The Lead Developer in London next week (June 22-24) or at SpringOne Platform (August 1-4) or Abstractions (August 18-20).

The Cardinal Virtues? of Technical Writing

First, a disclaimer: Medium served me this article, but it’s a year old. Weird. Nonetheless, I have things to say about the content.

The Virtues of Technical Writing, by a pseudonymous writer

Introduction

They are gleaned from a Bachelor of Science degree in Scientific and Technical Communication from the University of Minnesota’s Writing Studies Department, years of on-the-job experience, and lifelong self-guided study of the art and science of literacy. I share them here hoping only to bring further communicative light to the world. Heed them and prosper in all of your professional writing endeavors.

Coupled with the woodcut used to illustrate this article, this is exactly the kind of authority-derived advice that makes me gnashy. It’s all about sactioned knowledge and not the dirty fingernails of actually mucking with problems. I believe this person does do the mucking, but they’re not sharing that experience here.

In my experience (but lack of tech writing degree), software technical writing is a lot more like the pratfalls and triumphs of parenthood than any kind of art and science. Every child is generally similar in that they need food, love, and structure. Every child is vastly unique in how, why, and when they need those things. Software products are the same way.

Consistency

I’m not going to argue with this one. Consistency absolutely does matter, because anything else requires extra cognitive work from the reader. It’s our job to make their lives as frictionless as possible.

Thoroughness

always include a near over-abundance of information. Repetition and informational reconnoitering may feel redundant, but the confidence your readers gain from full insight into every step of the process will more than make up for the longer document.

No.

Let me repeat that.

No.

The more you make people read to get to what they need, the more likely they are to drop out. This approach addresses the needs of the long end of the tail over the vast majority of software users who are just trying to get this thing done so they can move on with their day. You need your documentation to be as short as possible while still covering the majority of scenarios. If you get questions or Stack Overflow notifications on some point you haven’t covered, then there is an audience for it, but otherwise, it’s probably just data for the sake of data.

Clarity

I’m also not going to argue this in the abstract, but I’m a little dubious about the absolute nature of assuming that removing words adds clarity. I’m currently editing a piece where the technical writers not only removed adjectives and adverbs, but also a bunch of definite articles. This is not actually useful, as it makes sentences a puzzle and not a seamless transfer of information.

My fourth grade teacher told me that the nouns and verbs are the muscles and bones of a sentence, and the adverbs and adjectives are fat. That’s a good way to think about it. Sometimes, a sentence needs a little plushness, a little padding, something to break up all the angular strength of what you’re saying. If each sentence is a perfect exact crystal, it’s like eating nothing but boneless skinless chicken breasts.

On the bright side, this is the first time that the user’s needs have appeared! So that’s a plus.

Hierarchical structure

The methods, style, and order of your hierarchical structure must first be universalized and then obeyed in every document if the implications of their design are to be understood by readers.

If your hierarchical style is not self-explanatory from the bottom level, you’re doing it wrong. Also, as I’ve been saying since 2012, very few people come to documents as documents. Instead, we encounter them as search results, and not all of the headings in the world are going to save your user if they can’t get what they need from the result returned to them.

We are not writing documents anymore, we are writing topics that are strung together. This is what Corilla is based on, this is what Madcap Flare and RoboHelp and every other modern writing tool that I can think of is based on. That’s because the basic unit of software documentation is no longer the document, or the man page, or the readme, it’s the answer. If your heading does not tell someone what question you are answering in the topic, be prepared to watch your bounce rate exceed your stick rate.

Introductory paragraphs

Agreed. Let’s not just plop some steps down without context. But you know what else you need? Next Steps. Now that you’ve done this thing, what are your increased options, your next configuration task, your results? If someone doesn’t know what they’ve done, can you really say they’ve done it?

Images and screenshots

Uuuuugh. No. Well, not a universal no. I agree that conceptual drawings can and should be used for multi-step processes. These images should be editable and have text labels that overlay the image if possible.

Here’s why we should NOT put images and screenshots in technical documentation.

  1. They are hideous to localize. You are adding thousands of dollars to a project when you do that, depending on your localization preparation and thoroughness.
  2. They are inaccessible. More people than you think are using screen readers, or their monitors cranked way up so the fonts are the size of fingerprints. Every time you say, “use the configuration settings from this screenshot”, a tiny exclusion demon gets its trident and stabs someone with low vision. Don’t do it.
  3. They change. It’s not that I haven’t tried to keep up with my developers, it’s that those charming individuals will move entire interface sections without telling anyone. The thing that is worse than not having a picture is having a WRONG picture.
  4. It’s 2016. We don’t need to show pictures of the screen because the odds are the user is looking at the help and the product on the same screen. Adding an image just gives you a recursive nightmare of non-flowing images next to the thing they’re describing.

Spelling, grammar, and punctuation

Fair enough, as long as you don’t fetishize them. Meaning is more important than form, every time. Sometimes I use sentence fragments for effect. Is that incorrect grammar? Sure. Is it effective at communicating my meaning? Absolutely, to English speakers.

If you find yourself convoluting to try to figure out how to comply with a grammar rule, the solution may not be to rewrite the sentence again, but just to tie a knot and go on.

I do care about punctuation consistency, especially around bulleted lists, but mostly that’s about the voice of the documentation, not The Rules.

Review and revision

I started writing this rebuttal at about 3. I expect I’ll publish it before 5. I expect I’ll iterate it.

Much like my developers, presenting a flawless product will get in the way of me presenting any kind of product at all. I have a system for tracking bugs in my documentation, and I fix and release. That’s all I can do. My review is essentially the same as an intergration test — does it compile, does everything in the package make it in, do I have any breaking errors? Beyond that, I would rather you had something now.


What’s missing

Where’s the user? Where in this whole system of virtues is the person we are supposed to be technically communicating with? When the user appears, they are an empty vessel, to be filled with information (Thoroughness, Introductory paragraphs, Images and screenshots) or running a race for understanding (Clarity).

As a technical communicator, my primary goal is to help people get things done.  If we can design software better so they don’t have to read docs, I have succeeded. If we can make docs shorter or more nimble so they can do their work, I have succeded.

My value is not in writing. That is merely a manifestation of my real value, which is empathic, meaningful connections that allow people to get on with their lives, while incidentally using our software. My value is as much reflecting users back at the developers as it is reflecting the software into the user’s context.

I appreciate that this person wrote up their thoughts, and as you can see, I agree with many of their points, but overall, I think an emphasis on technique over understanding is an easy, tragic mistake.

I could speak with the tongues of humans and angels, but if I have not love, I am but a noisy gong.

1 Corinthians  13:1