Sunday, December 4, 2011

Stick it in the wiki

We're a few months into the project and it's already happened. We've stopped doing documentation. We're programming, we're doing our TFS due diligence, we're writing our self-documenting tests. All good stuff. We're hitting Stack Overflow hard, but we're not really documenting anything. We're having spirited discussions about coding standards, but we're neglecting our shared documentation repository. We're struggling with gnarly integration problems between different platforms, we're writing in-depth emails to each other, but we're not taking a step sideways from the code and introspecting as we should. We're not bad people, but we're busy right now. We'll get to it, ok?

We're upgrading to @ReSharper 6.1 but we haven't contributed to the written culture of our team all week, hardly ever. We've just stopped. We all agreed when we started that it's something we should be doing, so therefore this hiatus is not borne out of any ideology, but rather is just a collective shrug of the shoulders.

What does it mean when a team starts neglecting the documentation aspect of their work, when they ignore their written culture?

Flickr photo
FlickrPaul Bourget (LOC), by The Library of Congress. Writing. It's what we do. Stick it in the wiki.

Are you part of the problem?

Like many a place I've worked in, we have a developer wiki here. I call it a wiki because that's what people call it, even though it's not really: it's a Sharepoint CMS. And like many places it languishes in obscurity as we work to get through our sprints. This is probably inevitable, as early development is characterized by rapid progression and scaffolding up initial infrastructure.

But before complaining about a problem, I find it a salutary exercise to examine my own contribution to it in the first place. For my part I quickly added some content to our team wiki, but then as quickly forgot about it. I went off and set up a group Diigo account and a Google+ Circle. That was because I think that links belong in a social bookmarking site like Diigo or Delicious, and Google+ is good for quickly hitting up the other guys for quick questions, etc. But I also let the wiki slide a wee bit because - yes, I'll admit it - it's not sexy, our poor old CMS. It is simply a fact that Sharepoint is uninspiring and unattractive, at least to devs that I've met.

It really is something only a mother could love, our wiki. Restricted to using IE unless one wants to hack away directly at the HTML whenever one makes a contribution, unless of course one is feeling fortitudinous enough to paste example code in, in which case manual HTML hacking is the rule whatever the browser, one approaches the wiki with fear. And since this is Sharepoint-generated-HTML I get the F.E.A.R. every time. Crappy old tech can turn people away from doing something they should be doing.

So can uninspiring motives: one way the purpose of a developer wiki has been explained to me is as something we'd need if a new developer joins our team, maybe because one of us is hit by a bus. If that's the main justification for your wiki, it's hardly surprising that devs concentrate more on solving immediate problems and less on worrying about implausible catastrophic hypotheticals. If they think of it as a resource they themselves will need before too long as the project gathers complexity then they are much more motivated to cultivate their project's written culture lovingly: it's in their own interest to do it, not in the interest of someone they haven't met yet.

My last job

In the last place I worked in, they had a strange relationship with their wiki. The devs begrudgingly acknowledged its existence, and would wonder at your naivety if you actually tried to follow any of the processes contained therein. After Brad, the tech lead, left in frustration two weeks after I started, it fell upon me to take over and maintain the wiki. I say take over, because it had been hosted on Brad's machine, which was now no longer switched on. I tried tidying the pages up, correcting some of the more egregiously out-of-date articles, and so on, only to be told at a morning stand-up that I "was not being paid as much as I was to edit a wiki". I said, fine: then please stop referring me to it to find out how things work, when everything in it is so clearly wrong. Let's have the new guys go around and waste people's time asking them why this does that, and why that goes over there, etc.

This was a team in deep trouble - during my short 4-month stay there were several departures before - mercifully - a troubleshooter was called in to salvage the whole enterprise. At one stage, two of the devs who were determined to flag their independence from everyone else in our team maintained a separate page with steps for - oh I can't remember - something to do with database scripts, and were allowed to get away with their passive-aggressive behaviour in the face of entreaties from me to put their work in the common repository. This was a team whose members couldn't bring themselves to agree on how to share information. The state of the wiki was a good indication of the culture of the team, and of the poor health of the project.

Overreliance on Stack Overflow

It's not as if the idea of reading about how to do things is an alien concept to developers in their day-to-day work. It's just that Google is so good that people find it easier to search for information by keyword than try and find it in the in-house repository. Nowadays, Googling for programming information usually means one thing: all roads lead to StackOverflow.

Like anyone interested in programming, I love Stack Overflow. It's been such a positive force for good since it hit our screens around 3 years ago. Nonetheless, I think it's a shame to see devs constantly browsing SO at work. Which you do. I mean, is SO going to be able to tell you why you've just wasted half an hour trying to get a service call to the in-house service working? Maybe, maybe not. But since this sort of boundary between different layers is where trouble can often arise, it's vital that any hard-earned wisdom here gets wiki'd. And that it's the first place devs look when they hit trouble.

Stack Overflow is fine when you have a discreet technical problem that has nothing to do with your project's particular configuration, but even then after a bit of browsing around for the right question (and of course, answer) you nonetheless probably want to document that issue, with its Stack Overflow Url (ooh, lovely and clean MVC route) in case someone else hits it, or you do again.

Flickr photo
FlickrJoel Spolsky and Jeff Atwood present at MIX09, by D.Begley. You guys are spoiling us.

Of course, the other case where you want to document your Stack Overflow activity is if you have actually asked a question and got a decent answer or two. This is harder than you'd think sometimes. But if you have successfully crowdsourced a small part of your work of course you should allow the other people in your team to find out about it without them having to accidentally stumble upon it. Hello wiki.

Keep the noise down

As important as it is to generate content in your wiki, it's also vital to do some gardening, to clear out the weeds. This week I took a look at a couple of pages I'd written very early in the project, and to say they were irrelevant to what we're doing now is being generous. Gone. Deleted. Turn that noise down. These pages were borrowing from devs' goodwill and patience, and repaying nothing.

None of this is easy. None of this is for free. Not every web developer likes to write. Not all of them blog. Many barely tweet (C'mon Sandra - do it!). And even if they did, they may not see the value in burying articles in a company wiki, too often a cold, forlorn place where knowledge goes to die.

If you have a dominant developer or a tech lead who doesn't like to document stuff, or just doesn't have the time, you may end up playing Boswell to his Dr. Johnson. Wiki as project biography. Without the wigs, hopefully.

But here's the thing: if you keep a good enough wiki, Sharepoint CMS, team blog, or whatever form your team chooses to document its work, you might end up with several blog posts worth of material practically written for you. Whether you are blogging from a low-level technical level, or more from a project management or architectural one, it should be all there: the reason you switched from Ext.NET to jQuery UI, afternoons spent arm wrestling with Entity Framework Code First, a love letter to ELMAH. Maybe if only for that reason, a dev might decide to really commit to the team wiki. As long as it's in there, it doesn't really matter why you're doing it.