Why I Speak at Developer Conferences

I don’t write code for a living, and I never have. Developer has never been part of my job titles, and my Github history won’t impress anyone. I think that’s why people are surprised that I speak at developer conferences — next month I’m going to RubyConf, PyconCA, and Nodevember.

When I started speaking at conferences, I thought I was only “allowed” or “entitled” to speak at technical writing and generalist conferences. As I got more confident in my messages, I realized that there is a lot of value in cross-pollination of ideas. As I talked to more developers, I realized that the talks they found the stickiest were not about how to do something, but rather, what it was possible to do.

Think about talks that you remember after the conference. Are they the bravura live-coding examples of how to execute something tricky or new? Or are they the talks about what you could do, how you could think about things in a different way, what might be possible in the future? The demonstration of current things is important, but so is the discussion of where and who we want to be in the. future.

Most conference committees seek to balance talks and speakers based on experience, representation, intended audience level, technical depth, and appeal to attendees, sponsors, and employers. We need to have deeply technical talks, and we need to have talks about mental health and accessibility and usability. it’s not either-or, it’s also-and.

So I speak at developer conferences to bring balance to the force. I also do it because I want to show up and be technical and expert and pink-haired in the world. I want to share my decades of experience with people who have poured their energy into learning different things. I think I bring value, and evidently conference organizers agree.

Have you thought about what you can add to a conference by being different? If you feel like you can’t compete because you don’t have anything new to say about the topics that are usually covered, consider covering a topic that you haven’t seen at the conference. If there are a lot of code demonstrations, consider doing a feature overview. If you have expertise in something that you can relate to the conference topic, sometimes it helps people grasp what you’re talking about in a different way. I have a talk about how knitting and documentation and how we teach code are all linked together.

If you’re a “non-technical” technical person, don’t let that stop you from proposing to conferences – you still have valuable and meaningful experience to share. If you’d like to brainstorm about it, go ahead and leave me a message.

Lady Conference Speaker Talk Wrap-Up

I was talking to Bridget Kromhout about her wrap-up process, and she inspired me to a) do a better job publishing my talk information right after I give it, b) talk about my end-of-talk process.

So, you have pitched a talk, gotten it accepted, written it, gotten on stage and given it, and answered any questions. You are about to come down off the adrenaline high and start second-guessing what it is you said. It is totally normal not to be able to remember exactly what came out of your mouth. Depending on how nervous a speaker you are, you may not have formed any particular memories, because we are terrible at forming coherent memories when we’re scared.

The slot after your talk, or the evening after, or the flight home, you want to publish your talk wrap-up. I think the ideal wrap-up consists of the following elements:

  • Your slides
  • Twitter reactions
  • Follow-up answers
  • Research sources/bibliography/image sources
  • Video

I do almost all my slides in Google Slides, with Slides Carnival. I do a new set for each talk, since I’ll end up adjusting length and emphasis for each conference. Immediately after I give the talk, I tweet out the public link to them. My slides also have extensive speaker notes.

The next few steps are much easier if you use Storify, an app that plugs into your browser. When I am researching a talk and have a reasonable belief that I’ll be using a page as reference, I click the Storify button to add it to my potential elements. I can also use it to capture tweets that will be relevant. After my talk, I’ll open Storify and look for tweets about the talk, whether with my Twitter handle, the conference hashtag, or the talk hashtag. I drag all the relevant tweets into the story about this talk at this conference, organize them, and then add the link to the slides at the top and the reference elements at the bottom. Then I click publish. I can always go back and edit that Storify to add the video when and if it’s ready.

In WordPress, Medium, LinkedIn, and several other platforms, you can embed Storify stories as part of the post, to raise the visibility and make sure it’s part of your platform as well as Storify’s.

Keep an eye out on your email. Conference organizers are quite likely to ask for your slides so they can sync them to video or publish them on the conference site.


There are a couple places that I want to improve my process — I have seen webpages that have two columns – one for the text of the talk and one for the slide. I feel like that would improve my web presentation and make it more accessible, but I have yet to find the WordPress/CSS magic to make it happen. Everyone I know who does it has hacked their own, and I want a turnkey solution.

I also want to start dedicating some money to getting talks professionally transcribed. What I write out and what I actually deliver are similar, but not identical, and again, I want to improve access for people who can’t or don’t want to watch video.


Here’s an example of one of my talk writeups: http://www.heidiwaterhouse.com/2017/05/26/the-death-of-data-signal-2017-edition/

Our tools shape our worldview, or Least-bad Confluence techniques

If you have been in a conference open space with me, you know that I make a terrible yuck face whenever you ask me to talk about working with Confluence. I have yet to work with an instance of Confluence that didn’t make my soul hurt. But it’s not really the technology’s fault if I hate it, is it? Isn’t it about implementation? Aren’t tools essentially neutral?

Yes and no. We talk about opinionated programming languages, but every tool has an opinion about how it should be used, a happy path. For example, the WordPress mobile app is great, and I love it for composing blog posts on the go – that’s what it was made for. But I would find it really irritating as a progress tracker if I tried to use it to replace Trello. Trello thinks in tasks and it’s hard to get it to show you the overall picture of a project. We can go through our whole toolchain like that — each piece of software we build or buy has a way it wants to be used, and although we can hack our way around that, it’s always going to be. more friction than using tools as they were intended.


Problem space

I’ve been to many DevOps Days in the last couple years, and I keep seeing the same pattern of problem.

  1. Documentation exists…somewhere, but no one can find it.
  2. People write documentation and no one can find it.
  3. Documentation is scattered across many locations and no one can find the parts they want.
  4. Standardizing or consolidating the documentation seems impossible because there’s so much of it, in so many places.

This is almost always in a Confluence shop — some people are using other wikis, some people have Word files, but the problem is really recurrent in the Confluence-using places.

Possible solutions

I have some suggestions for how you can make this better in your organization.

  1. Install a better search engine. The one that comes with Confluence is remarkably unhelpful at surfacing current, relevant data. It says it’s searching on relevance, but the returns are difficult to read and frequently so outdated as to be unhelpful.
  2. Break your silos. One of the ways that Confluence is opinionated is that it’s designed to work in silos. Development doesn’t automatically see marketing. Sometimes, this is intentional access control and sometimes it’s just an artifact of thinking in organization charts. Either way, it keeps people from being able to efficiently share information within a company. If you are setting up a wiki or CMS, make it as flat and open as possible. Separate items by task, not job title.
  3. Delete about half of what you have. If you do an analysis, I bet you’ll. find that there is a lot of outdated information. I don’t know what it is about wikis, but they are amazing as graveyards of information that has expired. I think it may be because web pages get refreshed periodically, but it’s been true of every wiki I’ve worked with that there is a bunch of old, wrong data.
  4. Put in analytics. See what people are actually using, and what they’re looking for and not finding. That’s how you know where you should focus your first efforts.
  5. Have one clear purpose for each document: Is it to help tech support answer questions? Is it to document the deployment process to increase pager duty depth? Setting a clear goal for you documentation lets you check everything against that standard.

But!

Of course you can’t implement all of those solutions. Not now and maybe not ever. But you can do some of them whether or not you have buy-in from the rest of the company. Define the purpose of your company and your job and your documentation. Once you know that, you can start working toward it. Next, let the analytics run for a while, and put together a report on them.

When you realize people are trying to search on something that exists and they can’t find it, upgrade your search engine. Once your team is actually using search, you can use the same analytics to strip out low-value or never-used data to make room for more.


What do you think? What tool have you noticed changing your thinking and process? This is one of the reasons I love Monument Valley – while it has predictable rules, it also plays with the dimensions of 2D and 3D space, and it surprises us with optical illusions based on the way we portray dimensional things on a flat screen.

Let’s think about how our viewpoint is constrained by our software, and whether we can spin our point of view.

The virtuous thank-you cycle

We talk a lot about vicious cycles, and how it’s easy to end up in bad places because the incentives are all bad, but let me tell you a story.

It’s a pleasant Saturday, my family is watching Star Trek: TNG together, and I’m in my home office, working on a side project and slightly resenting it. It’s the collateral for a workshop Carol Smith and I are giving at LISA about the non-technical part of interviewing, and we think it’s really an important part of helping people get jobs. So the workshop will be great and important, but I’m currently wishing I was doing something else. And then this comes across my twitter:

Marie says she uses the principles I espoused in that talk even when she starts side projects, like Call My Congress. Because she set it up to be easily localized, anyone could come through and easily add instructions in Spanish or Somali, without having to fight the project to do it.

I gave that talk 17 times. I took it to a different continent. I got most of my expenses paid, and I got an honorarium exactly once. I figure I spent 60 hours researching and writing it, and and 3-5 hours in prep and rewriting each time I gave it. I was working for myself, so no one paid me for that time.

A thank you note like this makes that all worthwhile. I give technical talks for the same reasons that novelists say they have to write – because it’s something burning in me, and I need and want to share everything I have learned the hard way so that other people don’t have to. In my grandiose moments, I think of it as reducing the entropy of the technical world, giving people a boost up the ladder. Most of the time I think it’s funny that all of my teacher-mother’s children have found our own ways to teach, far from school classrooms.

Now I have a job that pays me for development time for talks, and means that travel and conferences are not lost productivity for me, and that means the world to me, but most of the technical speakers you see at conferences are like I was — working evenings and weekends and taking vacation time to battle entropy with education.

I’m going to try to remember to do better about saying thank you, and thus spread the cycle of appreciation further and wider. A virtuous cycle perpetuates because the rewards are so good. Thank your mentors, and the friends who want you to expand your horizons, and the organizers who make safer spaces to speak in, and the bosses who don’t make you take vacation days. Thank them publicly and specifically.

Think Globally, Sponsor Locally

Possibly the most exciting thing about my new job as Developer Advocate (there are so many!) is that I don’t have to scramble and ask conferences to fund me anymore. That means that speaker funds can go to the next generation of up-and-coming speakers, independents, and folks who don’t get paid to go to conferences.

It also means that the conferences I go to is not a set restricted by people who can afford speaker sponsorship. I have had to turn down acceptances I was excited about because the conference just couldn’t afford to make it happen, and we were all sad. They wanted to have a range of speakers, I wanted to talk to their audience, but the cash just wasn’t there.

What does it mean to sponsor a conference, as a company? Well, you get your name on slides and promotional materials. Sometimes you get a couple minutes to tell people at the conference what it is you do. You get intangible benefits in good will from conference organizers and attendees. That’s all pretty hard to quantify. But just because something is hard to quantify doesn’t mean it isn’t worthwhile. The conferences you choose to sponsor say a lot about your values as a company. Sponsoring small, inclusive conferences is a relatively meaningful statement. You’re saying you care about the community, and about having a code of conduct, and about nurturing emerging or niche technologies.

Think about sponsoring at a huge conference, like AWS re:Invent. 30,000 people showed up in 2016. Logistically, and in every other way, that’s massive, and sponsorship is expensive, and the impact your company will have is dilute. You’re trying to get the attention of the people in your demographic, in the middle of a vast sponsor hall, in Vegas. You may get enough people to make it worthwhile, but it’ll be hella expensive.

Now think about sponsoring a DevOpsDays conference. Minneapolis is huge, at ~1300. There is a vendor room you can walk in half an hour and the people at the tables have time to talk to you, and are maybe giving a relevant talk. It’s a regional event, so if you’re an employer looking to hire, it’s great to find people, because you know they are already invested in the tech, and are in the area. It’s a way to connect with your community, and I don’t have the numbers to prove it, but I’m going to bet it costs companies a lot less than schlepping enough people to represent at the table to Las Vegas. Target was there, and Merrill, and Optuum. They’re signalling that if you work for them, they care about devops and you might get to go to local conferences, and they’re engaged. That matters a lot! Target is still doing rehabilitation on their local reputation after a set of bad decisions around IT, so it doesn’t hurt to have them showing up and working to be better citizens.

As a company, you should also think about sponsoring really small conferences – the 200-400 range, or even local user groups and meetups around your technology stack. Don’t do it because there’s an immediate payoff, or because you can chart a rate of return, but because it’s the right thing to do to nurture the community you draw from. The goodwill, expertise, community engagement, and candidate leads you get will be so much more valuable, dollar-for-dollar. It’s not always the decision-makers who go to these conferences, but they will be decision-makers eventually, because they are displaying exactly the go-getter values that you want by going to conferences. Think of this as contributing back open source code that you refined in house, only instead of features, it’s cash. Sponsoring these small conferences gives people who can’t travel a chance to meet and aspire and network and connect, and that’s immensely valuable to the circle of practitioners in an area and to the development of the technology as a whole. Working for a big company should not be the only way a brilliant Python developer can make connections with her peers.

I was inspired to write this because North Bay Python is looking for sponsors, and because Alterconf has been an astonishingly effective incubator for speakers, and is ending soon (but you can still say you helped!). I wrote it because I’m going to SeaGL, and they aren’t charging attendees at all. So many of my meaningful conference experiences have happened at conferences that are accessible to everyone, not just people with corporate budgets. Also, if you think about it, conference organizers are like the definition of social superconnectors, and they have Quite Strong positive associations with people who give them money to make the magic happen.

So what can you, a technical writer/developer/ordinary person do about this?

  • Talk to your marketing team about what matters to you. They are very smart, but not psychic, and they would love to hear about ways their sponsorship dollar could go further.
  • Volunteer for local conferences if you can. It takes a village to fold t-shirts.
  • Ask if you can spend recruiting money to sponsor conferences that specialize in the skills you’re looking to hire for. Looking for a functional programmer? Sponsor moonconf.

If you’re running a small-to-medium conference, reply here and I’ll try to put together a link roundup of conferences people could consider sponsoring. Don’t @ me if you don’t have a Code of Conduct, though. It’s 2017, people.

Also? Vote for your local school bonds and levies, while I’m advocating for spending money on systems thinking.

Also also? AWS Re:Invent? You’re charging $1600/ticket and you can’t provide childcare? Really? I mean, it’s not as bad as Grace Hopper. Don’t even get me started on Grace Hopper, but still.

Writing exercise

As a developer advocate for LaunchDarkly, I need to understand the product in a bunch of different ways – at a technical level to give summaries of how to make integrations work, at a business level to explain how feature flags can save time and money, and at a rhetorical level, so I can quickly gauge my audience and explain it to them in the most efficient way possible. Usually when I start a new project, I’m elbow-deep in documenting how it works and I have to work backward to why people want it to work one way or another. But this time I have the luxury of learning why a product adds value first.

I wanted to make sure I was grasping it, and as my friend Laura’s dad use to say to doctoral chemistry candidates, “If you can’t explain it to this ten-year old, you need to go back and work on it until you understand it yourself.” There is an apocryphal Einstein quote to the same effect. I think the modern version of making sure you really understand something by explaining it derives from Randall Munroe’s brilliant XKCD comic, Up Goer Five. Theo Sanderson built a little text editor with a linter that rejects all the words you can’t use, which is, um, almost all the words. But if you can conceptualize something really clearly, you may be able to describe it with the extremely constrained set of words. Here is my attempt to do so for feature flags:

Computers think in lines. Sometimes we want computers to think in a new line, but it’s hard to change lines all at once. We have to build the new line before we can change to it.

When we build the new line, we give it a cool name and hide it from the computer thinking. When we are ready, we change to the new line and lose the old one. The computer thinks the new line with the cool name is the only line. We can make the computer think with the cool name line or the old line any time. Cool/old, back and forward, when we want.

Sometimes, we want only some people to see the cool-name line. We put them in a cool-name group. Every time the computer gives them a thing, they get the cool-name thing from the cool-name line. Other people still get the thing from the old line. Who is happier? Cool-name group or old-line group?

We try to keep our computers happy and not too busy. Sometimes a new line of thinking takes more work for computers. Instead of making all the computers think the new line at once, which makes them slow and sad, we only tell some of the computers to think the new line. Then we add more and more computers thinking the new line, a few at a time. Soon, all the computers are thinking the new line, but none of them got too busy.

When we are finished with the old line, we make it go away. Now cool-name line doesn’t need a cool name anymore, it is just Line. We change its name to Line. When we want to write a new cool-line, we start over!

I’d love to see the results of some of you explaining your product using a thousand words. It’s not really useful as a way to explain things to people, since we want to teach customers our words and tune our language to their needs, but it’s very useful to show us if we understand something.

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!

Why on earth would developers WANT to write documentation?

This week I was at DevOpsDays Minneapolis, which was an amazing, warm, and inclusive event. There were at least three open spaces on documentation, communication, and related problems, and I didn’t propose any of them!

Minneapolis DevOpsDays 2017 logo

The question the devops world keeps asking, over and over again is,

How do I get developers to write anything?

There aren’t a lot of easy answers for this.

The first one is that if you care about developer-produced documentation, you should hire for it. But almost always, the people hiring are not the same as the people feeling the pain of missing documentation, so that may not happen.

The second is that you should hire someone other than the developers to write, if that’s important to you. I’m going to mention that all the times I’ve interviewed at Google, it was to be as an internal systems writer, documenting how things in the company work for other people in the company. Big, smart, companies hire writers for internal documents. But that is a tough budgetary sell.

The third, partial, answer, is that you make it significantly easier for developers to write. You give them forms and templates to fill in instead of expecting them to invent documentation theory. You specifically allocate writing time that can’t be budged for “one more tweak to the feature”.

Here’s the key problem though:

No developer has ever been fired for lack of documentation.

No developer I know of has gotten a bonus for documentation.

There is no stick. There is no carrot. There are a lot of competing demands on a developer’s time. Why on earth would they go do something that is not in their core competency just because you want it?

My instinctive response, whenever my kids want something, is to say, “It’s good to want things.” I think that is the instinctive response of most developers who are asked to do extra work. It’s not malicious, it’s just true. There is no reason they should do it – they won’t lose their jobs, the way they might if they prioritized writing over code. They won’t derive any benefit except the long-term and intangible one of being asked fewer questions. If they like being the source of knowledge, they’d be giving that away. If they like coding, you’re asking them to do something other than what they want. There is no upside.

So knowing that, how can we encourage developers to write documentation that we need?

First, reward it. Give people prizes for writing docs, or for throwing away or revising old docs. This needs to be something outside their usual compensation structure. Gift cards, time off, merit badges, whatever would be meaningful to that person. Ask them. They know what rewards them, because they use it to reward themselves.

A variety of rewards

Second, require it. I don’t mean “You have to write some docs or I will, uh, be disappointed in you.” I mean “The presence of documentation is a quality gate and you cannot release without it.” I mean “QA is using your docs as the test story.”.

Companies are never altruistic, humans are never purely motivated. We need to accept this and stop expecting people to do extra work because it’s the right thing to do, and start making the work not-extra, and the reward tangible.