Is this the gate you want to keep?

Today on Twitter, I said:

Guarded by succulents

That’s a lot of response for me. Like “Livetweeting @kelseyhightower” levels of reaction. So let’s stop and talk about that for a bit.

Honestly, I wrote the tweet because a group I respect put out a call for coders to help under-indexed coders do something that is entirely unrelated to coding, and I was frustrated.

Developers are not automatically the smartest people in any room, and I wish we would stop treating them like they were. It leads to all sorts of workplace toxicity. Yes, this is about the Google thing. And the Uber thing, and the thousand and one other sexist and racist things we could rattle off.

Certainly, deifying coding is a contributing part of coders acting like they’re little tin gods. Why wouldn’t they be cocky, if everyone they work with acts like their skill is all that keeps the company afloat? Heck, sometimes entire companies are “acqui-hired” just to get a functional team of coders – the supporting cast and the product are jettisoned, as if they had no value.

I’ve worked with several startups, and at a certain stage, investors stop asking about your coders and developers, and start making noises like maybe there should be a manager, or a financial officer, or a CTO who thinks strategically and not tactically. That’s because at some point, coders are people who exist to execute a vision, but somebody had better have a vision.

A vision isn’t just a rosy sales plan – it comes with understanding the industry, the problem space, the user experience, the way other people will see and use and touch the product. It comes with sales and marketing and QA and tech docs and support. If you are not actively courting the best support staff money can buy and paying them enough to show you respect them, you are, flatly, a fool. A good support person can make or break customer retention.

I know a lot of developers, and I mostly like them. They’re smart, and they sometimes have an amazing array of interests and passions, within and outside work. But they’re not magical. You can’t actually multiply productivity with them, and they won’t save your company. They can execute. The really good ones can execute and anticipate your strategy and build toward it. But developers don’t end up leading companies because they’re really good at Javascript. They end up in leadership because they didn’t let their coding skills be their entire definition. They worked on getting better at people, and meetings, and product, and even more people.

So every time you talk about teaching girls to code, or asking coders to help other coders with non-code stuff, or putting on a code school with no exploration of other aspects of software development, you’re saying that there is only one right way to be in technology. That is a narrow gate you’re setting up. I don’t like it. It makes me angry, and not just because I don’t code, but because it devalues the contributions of all the other people who make the magic happen.

It takes so much more than code to make a product happen.

Here’s to the PM who works hard to balance conflicting priorities and goes to dozens of meetings, to make sure things turn out as well as possible.

To the QA tester, who designs and runs endless tests in permutations you would swear no human would try, because there is no one more cynical about human intelligence than a tester, and they’re always right.

To the UX designer, who is so often dismissed as “making things pretty”, when they’re actually “making your product usable”. They run hours of human tests, watching and iterating until your product is almost invisible to the user.

To the writers, both technical and marketing, who spend all their time trying to figure out how to make the product real and relevant and useful to the people at the sharp end of the stick.

To the sales and marketing teams, who really do sweat the small stuff, who are actually kind of sick of fancy dinners and travel and airport seats, but who keep at it because they believe in this product and its ability to solve problems. Also sometimes they make us stickers.

To security, who may actually be the smartest people in the room, but have harnessed it all to righteous paranoia so that we don’t have to sit up every night worrying the way they do.

To support, who spend all damn day talking to people who are angry that something is broken, and still pick up the phone and say “How can I help you?” at the next call. They get everything from eyerollingly stupid user errors to actual arcane and intermittent bugs, and we expect them to know their way around our entire stack to troubleshoot. They know so much about the product and the customers, if only we ever asked.

To sysadmins, operations, cable pullers, and the invisible backbone of our infrastructure. We only notice you when things go wrong, but they go right so much more often, and we never notice the rough spots you sanded over already.

To finance and accounting and accounts payable and HR and company operations, who keep the lights on, and the fridge stocked, and who do get paged at 2 in the morning if the cleaning crew sets off the burglar alarm. I’m looking forward to the day I see an office manager tweet an #oncallselfie. They are amazing, attentive, organized, detail-oriented people, and I’m in awe.

To everyone who brings us food, cleans our toilets, vacuums at 2 in the morning, and otherwise lets us live like petty royalty – we owe you so much, and we are too self-conscious to even say thank you sometimes.

To management. Yes, management. Who go to so many meetings, you don’t even know. They’re out there making tradeoffs and calculations and doing the best they can with what they have and when you think about it, they have zero ability to make any difference in the product. All the responsibility, none of the power, at least in that direction.


The next time you hear someone talk about tech jobs as if they were all coding, stop and think a moment. I don’t want to devalue coding – it’s pretty cool. But I do want to pull all these other positions into the limelight of tech, and say,

“All of us make the product, and that’s awesome.”

Retrograde tooling

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

New employment: LaunchDarkly

Last week I told you about my exciting new job title, Developer Advocate.

This week, let me tell you about my exciting new employer! On Monday I started a job with LaunchDarkly, a startup that does feature flags as a service.

Feature flags are a way to distribute software with reduced risk. For example, if you had a holiday-themed CSS page that you wanted to activate after Thanksgiving, but you didn’t want the risk of deploying something that might break your holiday shopping experience, you could wrap the CSS in a feature flag. Using the feature flag, you can decide when to turn on the stylesheet. You can set the percentage of people who see the stylesheet. You can even hit the emergency kill switch for the stylesheet if it does cause problems.

Feature flags can also be used to test new features for part of your audience, or to replace conditional text, or to control which customers can access premium or paid features.

There are a bunch of implications that spin off from the ability to turn features on and off quickly and reliably – it changes some core thinking about what deployment is, how we think about a product, and what we do when something goes wrong. I’m really especially looking forward to working with customers to make sure that we are using and respecting their use cases. For example, while I was at DevOpsDays, I ran into someone who asked me how LaunchDarkly worked with HIPPA standards. I get to either find or write a white paper that gives them coverage for their needs.

It’s exciting to be an an inflection point in how we think about things. It’s happened to me a couple times — full disk encryption, multi-cloud management. I think this one may be another one. Ask me about it!