I’m quite the wiki enthusiast. I was an early editor on Wikipedia; I created several articles on really common topics, I got Featured Picture on a few photos I plucked from free sources, and so forth. I’ve run my own wikis since 2005. The biggest, at its prime, got a couple hundred thousand hits a month and had periods with 25-30 concurrent users; it was used by students in a classroom environment.
So, at my software development jobs, tending the wiki – or creating it, if it doesn’t yet exist – is a natural fit for me.
And at each job, I’ve heard comments which suggest that maintaining the wiki is low-value work, akin to picking vegetables or something. Allow me to exercise that analogy a bit: people who pick vegetables feed all of us, and there are racist undertones to presuming that picking vegetables is low value work.
Here are a few paraphrased comments:
Your smartypants talent
- “Sure, spend a little time keeping the wiki updated. Just don’t let it become a full time job. You’re a smart guy and a good developer – it’d be nice to use those talents as much as possible.”
- Translation: working on the wiki – the closest thing many companies have to a single repository of information – is low-value work.
- Translation: programming is some of the highest-value work in the company.
- Translation: building and organizing a repository of domain knowledge doesn’t require smarts – intelligent employees are best deployed elsewhere.
Often, I find that every level of management has no idea how much of a toll it takes when employees who need information can’t find it. It’s not just lost time, it’s reinvented wheels, well-intended but doomed (and somebody knew it five years ago) projects, and ultimately lost dollars.
When it comes to documenting code, if the programmer has talent at writing – some do, some don’t – who better to document all that complex institutional knowledge tied up in code so that it can be understood six months or six years later?
Oh, and why has only one company I’ve ever worked at, perhaps coincidentally the one with the highest Joel Score1, had a tech writer? And have you noticed, if you’ve been lucky enough to meet any, that a lot of tech writers are women? Maybe it’s because managers are more comfortable hiring women for “low-value work.” :|
I hate wikis
- “I hate wikis.”
- Translation: “I’d prefer you developers comb through our department’s information silo for knowledge rather than take a few minutes of my department’s time to link important stuff into the wiki.” Note that software engineers typically do not ask product managers, support personnel, or executives to comb through our source code.
This was said to me by someone outside my department, but I’ll look at both sides. Some engineers have this attitude too. I am speaking of the “Code Is Self-Documenting” cult. Bullshit. Complexity dictates that self-documenting code will never be enough. Your code depends on other people’s code and on APIs. How? Which? Why? And why not in this more-obvious way – i.e. why did you put up this fence? (Read on.)
unicorns people like project managers who need to understand the hows and especially the whys of code without necessarily being able to read it fluently? If you do not document the hows and whys of your code in prose, your software is not complete.
This is starting to sound familiar
- “I had a beer with Jen (ex-employee) last weekend and she said engineering spent two months on this projeect in 2009 and rejected it because _____.”
- Translation: “Jen just made me realize engineering wasted the last two months again in 2014 because most of the staff turned over in five years and all that knowledge walked out the door, and it wasn’t written down at all – much less organized, categorized, and made searchable.”
This frequently comes with the territory of reinventing wheels. Wheels may be reinvented because the old company wheel invention attempt was forgotten, or because a programmer is too short-sighted to use one of the 17 mostly-correct wheels on the shelf. The latter is a process and privilege problem; the former is a documentation problem.
It also tends to come with the disasters caused by taking down a fence without knowing why it was put up. The lack of knowing why the fence was put up is a documentation problem. The taking it down without a thorough and costly investigation to determine why it was put up is a management and a budget and often an ego problem, all of which can be avoided by documentation.
Code documentation tools already exist
- “We can just use [pydoc|javadoc|readthedocs].”
- Translation: “I conceive of the wiki as write-only and don’t understand it as a valuable space for cross-departmental communication.”
This objection is frequently leveled by engineers or their managers along with the Self-Documenting Code nerds. So let me put it to y’all this way: precious few from sales and not many from support are ever going to peruse your API docs. (You do have those, right?) And few outside engineering are going to peruse your software design and implementation docs. (You have those, right?) And you’re not going to start spending an hour a day on Zendesk committing support activity to memory.
With this view, programmers overlook the biggest consumers of implementation and API docs – the programmers themselves. I have already stated that “self documenting code” is insufficient to record the hows and whys of complex systems. When half “the team” moves on to work for Twitter and Joe Schmoe gets hired out of Hacker School, why should he have to spend 20 hours deducing – possibly incorrectly – the hows and whys of product implementation? That’s stupid and it’s a waste of money. And seriously? Shut up about building character in greenhorn programmers. That’s a boring, overplayed good ol’ boy argument if I ever heard one. It’s about as fresh and insightful as a bacon joke.
Collaboration across departments
Here’s a more positive example of where using wikis for cross-departmental communication can help immensely. Let’s say support personnel start wikifying problems and solutions to recurrent tickets that rarely make it to engineering because there’s a workaround, or because the problem isn’t very bad, or because the customer can be talked down. We all know those kind of tickets. Once they inevitably do escalate, there could be a treasure trove of debugging clues to work from in the wiki because support wrote a few down on all 17 prior instances the problem was “solved” with a workaround. Support people are ace, but just like programmers, they forget what the hell they were thinking about a few weeks ago – unless they wrote it down. If the problem didn’t get to engineering until the 18th time, the programmer either gets all clues because they are in the wiki, or she gets the 4% of all clues which the support agent happened to remember while typing the ticket.
And there’s more. Cross-departmental communication is one of the biggest money-saving potentials of company-wide wiki adoption. If product owners (you have those, right?) start noodling over their roadmaps in the wiki, programmers or executives watching the recent changes can promote good ideas faster and head bad ideas off at the pass. It’s like watching the commit log, but for the part of the company you wish would’ve told you they promised an NP-complete feature at FooCon ’14.
Git ‘r dun
For whatever reason, there are always some people who will resist the adoption of an internal corporate wiki. Sometimes they’re high-up enough that one has to route around the damage; even if they’re not, though, there may be low-level resistance. Typical bad past experiences with wikis is that somebody put one up and then nobody used it, or that it became slowly bloated with cruft. (If people maintain wikis, they won’t be too crufty, which is probably a primary point of a future post. You should click around on
WikiPatterns.com the archive of WikiPatterns.com, which is evidently dead and gone, so much the worse.)
The point is, wikis are great, but you have to invest care and feeding to receive dividends from them. You have to barnraise a wiki, use it and keep using it, keep it gardened, and slowly but steadily promote it for interdepartmental communication.
The other point is, a well-maintained wiki is a perfect example of working smarter, not harder. Even if you have to (gasp!) pay a tech writer to do the gardening on your wiki, there’ll be rich payback in saved time for every department which adopts the wiki as a common sharing platform. Saved time is saved money. Maybe more importantly, saved time is saved opportunity cost.
The corollary point is, maintaining institutional knowledge is not low-value work, and whether it’s engineering, support, or your unicorn tech writer doing that gardening, wikis are a great tool because people can just jump in and contribute. But documentation must be valued first. If you can’t get enough of the company to understand the value of documentation and subsequently make a beachhead at some kind of collaborative documentation, you’re at a badly-run company and you should probably look for another job.
1. Gotta love how StackOverflow closed it as “off topic.”