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/

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.

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