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

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

What is a documentation architect?

When I was at Write the Docs 2015, several people asked me about the title I have in my LinkedIn heading: Documentation Architect.

What did I mean by that? How is it different than content management or development architecture?

What a documentation architect isn’t

A documentation architect isn’t psychic. They can’t figure out your business needs unless you tell them.

They aren’t necessarily managers. They are designing the documents and process, not the team to build out the documents.

They’re not community managers. That’s a underrated specialty that combines amazing amounts of patience, charm, and detail-orientation. You should have a community manager, but it’s very difficult to combine with document architecture.

It’s not data architecture. The positions seem superficially related, but in this sense, data is the communication software has with itself and other software. Documentation is the communication software has with humans.

What a documentation architect is

Technical writing, like most jobs, is a combination of disciplines in different proportions. I can set up a documentation set, choose a documentation tool, predict usability pitfalls, monitor a translation agency, and conduct user testing.

I also have some less tangible, but equally important skills for building an organization’s first documentation set. I have enough moxie to tell people they are slow in getting their documentation going. I have seen enough successes and failures to have design models for several delivery methods across several industries. I can extrapolate from meetings what is most likely to need documenting in a month, or three, and what we should do about that.

Much like a software architect, I can build something novel, thought-out, and designed to guide less-experienced creators to assemble a product that will succeed over a period of time. Also like a software architect, I need to understand both the business needs of an organization and the skill sets required to accomplish my goal. I’ve come to realize that this form of architecture is about systems thinking and how the pieces come together to form the whole.

The other aspect of my specialty is experience. I don’t just understand technical communications problems intellectually, I have failed and succeeded at almost every type of project you can name. I’ve been doing this for long enough to know the failure modes of so many more projects than newer writers can have had time for. I also have had enough experience in different fields and organizations that I can identify nuances that more settled writers have not been exposed to.

When you are looking for a writer, or a user experience designer, or a developer, ask yourself if you are interested in someone who can learn and grow with your product, perhaps with a little guidance, or whether you are looking for someone who can understand and build aspects of the product in partnership at a higher level. Making that distinction will save you a lot of time both in the hiring process and when you are working with the new hire.

(cross-posted from LinkedIn)