In October, I attended HydraConnect. To my relief, it was not a networking event for evil comic book characters, but rather an in-depth conference for people running the Hydra software, which is used in higher education (and other library-like places) to organize digital collections.
When I walked in the first day, I didn’t even know that much. I’d been contracted to attend the unconference days and add a technical writing perspective to a distributed open source project. I wasn’t sure if I would actually add value, but it seemed worth the experiment, and I learned and taught a bunch of things, which I will summarize here.
Your documentation needs a lifespan
There are two problems in software documentation:
- Getting anyone to do it.
- Getting rid of it.
This is especially true in distributed open-source projects because there are many people contributing, but seldom a firm hand disposing. My proposal is that you PROGRAMATICALLY make your wiki pages expire after a year to trim down your documentation cruft and help keep all your docs accurate.
Scenario: You sit down and check your dashboard. Three notices appear for pages expiring this week. You click on the link to the first one. It is a workaround for a bug that has been patched. Do nothing. This data should die. The second one is a valuable tutorial that you know people still use. You check to make sure it still looks accurate, and click the Renew button. Safe for another year. The third link leads to a requirements page that should get updated now that some of the software mentioned is too old to be supported. You edit the page to be accurate and click Renew.
I came up with this idea because of some work I’d done years ago with people interested in sunsetting personally identifiable data. This is not quite the same as Right to Be Forgotten, it’s more that just because we can store an effectively infinite amount of data doesn’t mean we should.
Do you think there are actually 36 million people working for the government? No, but anyone who has worked for the goverment in the age of data had their information collected and NEVER PURGED. A huge part of that vulnerability is because our data never expires.
Data should have a lifespan. Technical data should get reviewed every year. Credit data should roll off after seven years. Your entire childhood posting history should get wiped when you turn 18. If we were more mindful about this, we’d have cleaner docs AND fewer horrifying data breaches.
Your documentation should get treated like code
This is not a new concept, but it’s especially useful for distributed teams.
- Keep your docs in a repository
- Write bugs against them
- Include them as part of features
- Write tests against your docs. If a novice user can’t follow your directions to do a task, you are not done. You can also use your docs as a test. If you follow the directions and the thing doesn’t install, you need to find out where the problem is.
Good examples are as important as good explanation
I could spend 300 words explaining to you how I like my peanut butter and jelly sandwiches made (toast, raspberry jam), or I could hand you my sandwich and let you see for yourself how it works.
Many people need that concrete example to understand what is possible for them to accomplish. Some of my current favorite documentation are the Swagger API docs. They are not very wordy at all, super minimal, but you get a sample site that works, and then you can play with it, and the documentation is all baked into that. I can see how it’s supposed to work, instead of following a process and hoping I get it right enough to work.
Search is how new users learn
When you get stuck on a new problem, especially if you’re not sitting next to someone who can answer your question, what do you do? Most developers and IT people I’ve talked to Google it, almost as a spinal reflex. If you are not doing internal analytics and designing internal SEO around that, then Stack Overflow is doing a better job supporting your product than you are. That’s not catastrophic, but it’s not great, either.
Set up analytics on your wiki, your web page, your help, wherever you are storing your documents, and start watching the search terms people are using. If your documents don’t answer the questions, write more. If the queries are using the wrong language, add better tags and keywords to your documents so they’re findable. I’m really glad someone wrote that, but it is a tiny bit worse than useless if no one ever finds it.
Drawing the elephant is better than explaining one piece at a time
Do you know the story about the six blind men trying to explain an elephant? One gets hold of the ear, and says, “I percieve that an elephant is very like a fan.” Another finds the elephant’s flank and deems it wall-like. Each person has a different experience of the elephant and even talking to each other, they can’t conceptualize “elephant”. Is your documentation like those people talking to each other? Has anyone provided a picture or description of the elephant? High-level conceptual topics are both difficult to write and technically complicated. You have to understand both the audience and the product. But without that description, you just have a bunch of disparate tasks.
Which leads me to my next point…
Context increases compliance
Knowing why I’m doing something makes me much better about doing it. I don’t let strangers poke me with needles, but I do get my flu shot, because I have enough context to know that it is the lesser evil.
If you’re asking people, especially volunteers, to do work, you need to be able to explain how their effort is going to be a benefit to the organization. It doesn’t need to be An Epic Explanation, just a little something to guide people. “Let’s get these chairs stacked out of the way for the karate class coming in.” is much more contextual that “We need these chairs in stacks of four.” Be sure you are providing acessible context for the product and the project.
Summary
Distributed teams that are not specialist writers can still create documentation, but they need to get rid of old docs and they need to have a clear vision of what they are doing and why.
Postscript
I really enjoyed the experience of the conference. Badges with pronouns! Other women, of all ages. But I also enjoyed being a technical writer at people. I’d like to do that again, for other projects that can’t afford a writer but do need a writer perspective
(crossposted and updated from LinkedIn, thanks to Sumana for the nudge)