December 17, 2016

Day 17 - Write it down or suffer the consequences

Written by: Heidi Waterhouse (@wiredferret)
Edited by: Matt Jones (@CaffeinatedEng)

Is there a terrible, tangled wiki that resembles the brambles surrounding Sleeping Beauty’s tower? Are there three magical and essential post-it notes that would be catastrophic to lose? Does onboarding someone new mean days spent trying to explain things that you just know?

If any of these sound familiar there may have a documentation problem.

This is probably not actually news to you. You may already be aware your documentation sucks and is hard to use, but fixing it may appear to be a monumental amount of work, and a general pain in the butt, and honestly, must we?

Well, no. I’m not your parent, I’m not going to make you do anything. But I am going to explain why it may work out better in the long run, and how to do it with a minimum of misery.

Why it matters to have good documents

Do you live in fear of the metaphorical bus? That’s the bus that could take out a key person who has the network map in their head. The bus can also be a surprise termination, a lottery win, even a scheduled vacation. The point is that you didn’t realize that you were dependent on this one person until they are irretrievably gone.

Or, on the flip side: Would you like to be able to take a vacation without your phone? Because you’re never going to be able to do that unless you are replaceable by documentation.

Humans store information in their brains in a set of fascinating ways, including mental maps of where they can go to look up auxiliary information. If you are depending on someone knowing how to find a key document, and they’re gone, it’s as if the document never existed at all. Think of it like RAM. When someone leaves an organization, it’s a reboot, and all the pointers to the information are destroyed. The information may still exist, but we’ll never know, because it was stored in the volatile memory of grey matter.

It is hard to get the budget to hire someone for internal documentation, even harder than it is to get the headcount to hire someone for user documents. It would be faster and easier, but it doesn’t happen. So you are going to have to be your own Mario here, and save yourselves by writing down what needs to be saved.

Why your documentation (probably) sucks

  1. It’s not findable or searchable. No one knows where to look for it, and if they do look for it, they can’t find anything in it.
  2. It’s describing a solution without mentioning what the problem was. Or there’s no narrative at all, it’s just a table of information that is expected to stand alone.
  3. It’s wrong. Not all of it is wrong, only 10% is wrong, but you don’t know which 10%.
  4. It’s old. Do we even have any NT servers anymore?

Fixing searchability

Do you have any automatic indexing turned on? Do you have a search engine installed and indexing your help? That would be a great start. Many of the wikis used in a corporate environment are unfriendly to robots and make it hard to generate an index. SharePoint is pretty much the worst for this.

You also need to start adding symptoms to your solutions pages. The idea that makes Stack Overflow so effective is that the search is on the problem, not the answer, since obviously the answer is not known.

You may need to have someone restructure your documentation organization. Go through and group things logically so that people can find things by serendipity. This group of documents is about server configuration, and this group is about firewalls. Even if the first firewall document doesn’t answer your question, the next one might.

Fixing a lack of narrative

I love a good table of settings as much as the next person, but it’s important to give people a little context as to why they want these settings, or what the reasons for choosing them may be. You don’t have to do a whole sweep of the documentation set now, just add that detail in the next time you open a page to update the settings.

You can also create a page to string together existing documents in a sequence. Open a new page, put in a couple sentences about what the goal of this procedure is, and then add a link to the existing data. Alternate links and context until you’ve walked someone through a procedure. Imagine how much time you’re going to save by doing this for your onboarding procedures! So much less talking to the new hire about how and why we use Jenkins this way.

Consider taking a page from the Agile playbook and writing up stories about how people might want to use this information. “As a sysadmin, I want to be able to open a port on the firewall.”. What information would it take to be able to do that? Can you assemble it all together on a page titled “Opening a port on the firewall?”.

Fixing old or wrong information

Almost no one writes down wrong information. Instead, information becomes wrong over time. This could be due to changes in the network, software, or human process chains. The problem is, it happens invisibly, and unless someone is actively maintaining the documentation, no one will ever know.

The outdated information can be fix as you come across it, if you know about it. You can also configure your pages to signal how old they are or how long it’s been since they were last updated. It would be great if is was easy for you to see at a glance that a page hasn’t been updated in the last decade, or even the last year.

Make it social. Get your whole team together for a documentation hack day and all of you grind through what you have and update it. It’s more fun when it’s not a solo task.

To sum up

Scripting things takes more time on the front end, and gives you so much free time and mental energy on the back end. Writing documentation is just a very basic form of scripting out behaviors of humans instead of machines. Do yourself a favor on the back end.

No comments :