How to document your job

I was recently talking to a coworker who is in the middle of a large project to document her job. The goal is two-fold: to give teammates the ability to cover for her when she’s out of the office and to improve the onboarding experience for new team members. She has her manager’s support, but it’s a large project. She finds it difficult to make progress, in part because she doesn’t particularly like writing. As a result, the deadline keeps slipping further out.

I won’t claim to be the best documentarian, but I try to always leave my successor with better documentation than my predecessor left me. I’d like to think I’ve succeeded in that. In some cases, the bar was pretty low because there was no documentation at all. At any rate, this post is a collection of things I’ve learned over the years. This is an opinionated post and does not necessarily represent the One True Way to Document Your Job™.

Writing

  • Separate the why and the how. You have two separate audiences: someone filling in for a day or two and someone taking over the role. The information they need is very different. A person covering short-term probably doesn’t need or want to know the whole history of a process. They just want to know the steps they need to take. On the other hand, your replacement will benefit from a greater level of explanation. They’ll want to know why the steps are they way they are. In particular, knowing what didn’t work well in the past is a good reference to help them avoid re-learning that lesson later.
  • Start at a high level. If you cover the broad stuff first, that gives your reader something to work with, even if they need to ask you or someone else to help fill in the details. On the other hand, a detailed list for process A does nothing to help with process B. Starting at a high level also allows you to…
  • Write small chunks. You don’t need to write everything in a day. Starting with higher level concepts allows you to break the role into a few key areas. From there, you can break it down further and further.
  • Limit the work in progress. Similarly, you don’t need to write everything at the same time. if you work one one or two concepts at a time, you can get those sufficiently done and move on to the next. Yes, it’s a bummer if the one of the incomplete concepts is what your coworker needs to cover a sick day, but some fully-complete documentation is generally better than a lot of woefully incomplete documentation.
  • Avoid duplication. The more places the same information is recorded, the more likely it will become out of date. If documentation for something already exists, link to the authoritative source. You can provide some basic context around the link, but minimize the amount of copy/paste you do.
  • Write as you learn. If you’re just getting started, try to write as much as you can as you learn it. That way, you don’t end up assuming knowledge that your reader won’t have. If you’re learning from someone else, this also gives you the opportunity to let them verify it.

Verifying

The first time you write documentation, it will almost always be incomplete. You’ll want to get feedback to help improve it. This turns out to be another benefit of small chunks with limited work in progress. It’s almost like Agile was on to something here!

  • Trade places with a coworker. If you can (this requires management support for sure), swapping jobs with a coworker for a few hours gives you the opportunity to see how the documentation performs in real life. Doing it while you’re still around means that the documentation has been tested before you have a sick day or vacation. If there are problems, you can answer them without being inconvenienced.
  • Get feedback quicky. Even if you don’t swap roles, at least let someone look at it as soon as you’re done writing. This way everything is fresh in your mind as the questions come up.

The mechanics

You may have noticed that I cleverly avoided discussing the technical aspects. Do you write a wiki page? A word processor document? A standalone note taking app (like CherryTree)? Rendered HTML on a docs site? I leave this as an exercise for the reader. They all have benefits and drawbacks, so whatever works best for your team is the right answer. If people can’t find or update the documentation, then why did you bother writing it?

Fixing a lack of documentation

In their 2016 developer survey, StackOverflow said poor documentation is the second-biggest problem faced by developers. 34.7% of respondents reported documentation as a challenge in their daily work. It’s not clear if that is internal documentation or upstream, but in either case the pain is largely self-inflicted.

Just as not everyone can write good code, not everyone can write good documentation. It’s a skill that requires practice, experience, and some talent. But the best documentation is what gets written. Documentation often has to start with the developer, even if someone else is responsible for cleaning it up.

The developer culture must embrace documentation. Test-driven development says write the tests first and code to the tests. Documentation-driven development is similar. We can argue about which should come first, but I’d suggest the documentation should inform the writing of the tests. Essentially, the documentation is the use case: the business reason you’re going to write code in the first place.

Writing documentation isn’t fun for a lot of people, so fostering a documentation culture is not easy. You can’t just say “thou shalt document” and expect it to happen. It has to be something you actively enforce. Your pull request doesn’t include documentation? It’s not getting merged until it does. You haven’t written a word of docs all year? No raise for you.

Once documentation takes root, though, it can be self-reinforcing. In the meantime, you do your users and your future self a big favor by making the effort now.

Documentation formats and speaker interviews

In lieu of actual content on this blog, allow me to introduce you to some recent posts I’ve done for Opensource.com:

Screenshots in documentation

I’ve spent a lot of time at work lately writing documentation or getting others’ drafts into our preferred format. I’ve written and consumed technical documentation quite a bit over the years, so it’s no surprise that I have a few opinions on the matter. One of my opinions is that screenshots are often used as a crutch to support poorly-written docs.

I shared this thought and got a little bit of pushback, so I thought it was worth expanding on. I’m not opposed to screenshots. In fact, I’m quite in favor of the judicious use of screenshots (if for no other reason that sometimes it’s nice to break up the wall-of-text). But showing the same window with and without text entered into a text box is excessive.

Pictures may be worth a thousand words, but they have a lot of downsides. Well-written documentation can be followed without a picture, which is very important for the visually-impaired who rely on text-to-speech tools. Text strings are much easier for translators to handle. That’s not important for all documentation, but can be very important if you have (or want!) international customers or contributors. Images are also less awesome in version control systems (which you’re totally using, right?)

A friend asked how I felt about videos. If they’re used in concert with text-based documentation, I prefer them to static images. Videos can provide visual and audio cues, which help accessibility. Videos also more obviously show how to manage complex interactions. Of course, the question that arises from this is: if your interactions are so complex as to require video explanation, do you need to fix your UI/UX?

The target audience matters, too. Technical users require fewer visual aids than unsophisticated users. When you write your documentation, use as many screenshots as you need, but no more than that.

FAQs are not the place to vent

I’ve spent a lot of my professional life explaining technical concepts to not-necessarily-very-technical people. Most of the time (but sadly not all of it), it’s because the person doesn’t need to fully understand the technology, they just need to know enough to effectively do their job. I understand how frustrating it can be to answer what seems like an obvious question, and how the frustration compounds when the question is repeated. That’s why we maintain FAQ pages, so we can give a consistently friendly answer to a question.

You can imagine my dismay when my friend Andy shared an FAQ entry he found recently. A quantum chemistry application’s FAQ page includes this question: “How do I choose the number of processors/How do I setup my parallel calculation?” It’s a very reasonable question to ask. Unfortunately, the site answers it thusly: “By asking this question, you demonstrate your lack of basic understanding of how parallel machines work and how parallelism is implemented in Quantum ESPRESSO. Please go back to the previous point.”

The previous question is similar and has an answer of of “See Section 3 of the User Guide for an introduction to how parallelism is implemented in Quantum ESPRESSO”. Now that’s a pretty good answer. Depending on the depth of information in Section 3, it might be possible to answer the question directly on the FAQ page with an excerpt, but at least pointing the visitor to the information is a good step.

I don’t understand getting frustrated with a repeated FAQ. If the answers are so similar, copy and paste them. Or combine the questions. FAQs, user guides, and the like are great because you can compose them in a detached manner and edit them to make sure they’re correct, approachable, and not jerkish. FAQs are an opportunity to prevent frustration, not to express it.

Parsing SGE’s qacct dates

Recently I was trying to reconstruct a customer’s SGE job queue to understand why our cluster autoscaling wasn’t working quite right. The best way I found was to dump the output of qacct and grep for {qsub,start,end}_time. Several things made this unpleasant. First, the output is not de-duplicated on job id. Jobs that span multiple hosts get listed multiple times. Another thing is that the dates are in a nearly-but-not-quite “normal” format. For example: “Tue Mar 18 13:00:08 2014”.

What can you do with that? Not a whole lot. It’s not a format that spreadsheets will readily treat as a date, so if you want to do spreadsheety things, you’re forced to either manually enter them or write a shell function to do it for you:

function qacct2excel { echo "=`date -f '%a %b %d %T %Y' -j \"$1\"  +%s`/(60*60*24)+\"1/1/1970\"";

The above works on OS X because it uses a non-GNU date command. On Linux, you’ll need a different set of arguments, which I haven’t bothered to figure out. It’s still not awesome, but it’s slightly less tedious this way. At some point, I might write a parser that does what I want qacct to do, instead of what it does.

It’s entirely possible that there’s a better way to do this. The man page didn’t seem to have any helpful suggestions, though. I hate to say “SGE sucks” because I know very little about it. What I do know is that it’s hard to find good material for learning about SGE. At least HTCondor has thorough documentation and tutorials from HTCondor Week posted online. Perhaps one of these days I’ll learn more about SGE so I can determine whether it sucks or not.

Deploying Fedora 18 documentation: learning git the hard way

If you haven’t heard, the Fedora team released Fedora 18 today. It’s the culmination of many months of effort, and some very frustrating schedule delays. I’m sure everyone was relieve to push it out the door, even as some contributors worked to make sure the mirrors were stable and update translations. I remembered that I had forgotten to push the Fedora 18 versions of the Live Images Guide and the Burning ISOs Guide, so I quickly did that. Then I noticed that several of the documents that were on the site earlier weren’t anymore. Crap.

Here’s how the Fedora Documentation site works: contributors write guides in DocBook XML, build them with a tool called publican, and then check the built documents into a git repository. Once an hour, the web server clones the git repo to update the content on the site. Looking through the commits, it seemed like a few hours prior, someone had published a document without updating their local copy of the web repo first, which blew away previously-published Fedora 18 docs.

The fix seemed simple enough: I’d just revert to a few commits prior and then we could re-publish the most recent updates. So I git a `git reset –hard` and then tried to push. It was suggested that a –force might help, so I did. That’s when I learned that this basically sends the local git repo to the remote as if the remote were empty (someone who understands git better would undoubtedly correct this explanation), which makes sense. For many repos, this probably isn’t too big a deal. For the Docs web repo, which contains many images, PDFs, epubs, etc. and is roughly 8 GB on disk, this can be a slow process. On a residential cable internet connection which throttles uploads to about 250 KiB/s after the first minute, it’s a very slow process.

I sent a note to the docs mailing list letting people know I was cleaning up the repo and that they shouldn’t push any docs to the web. After an hour or so, the push finally finished. It was…a failure? Someone hadn’t seen my email and pushed a new guide shortly after I had started the push-of-doom. Fortunately I discovered the git revert command in the meantime. revert, instead of pretending like the past never happened, makes diffs to back out the commit(s). After reverting four commits and pushing, we were back to where we were when life was happy. It was simple to re-publish the docs after that, and a reminder was sent to the group to ensure the repo is up-to-date before pushing.

The final result is that some documents were unavailable for a few hours. The good news is that I learned a little bit more about git today. The better news is that this should serve as additional motivation to move to Publican 3, which will allow us to publish guides via RPMs instead of an unwieldy git repo.