24th September 2013

Knowledge sharing

Arguably the most important thing to get right as a team, whether you are leading it or have just joined it, is how you share knowledge. Without a good strategy you can end up over reliant on long standing staff or worse - alienating new starters.

I hope I don't have to convince you that neither of these are a good place to find yourself as an organisation. Long serving staff may like the idea of being 'unsackable' but the business sure doesn't and the extra stress of always being the only 'go-to' guy/gal is not something to revel in in the long term [1].

Don't think this doesn't apply if you're an independant freelancer. It isn't just people you need to spread knowledge across. It's also time. A year after you did something you may want to reuse it or need to refresh your memory rather than re-learn it.

What is Knowledge?

All I know is that I don't know nothing Operation Ivy

So what are we talking about?

• Local dev configuration and setup details
• New technologies and approaches
• Where to find existing (reusable) code solutions
• Hosting and access details for projects
• Particular nuances of project implementations

How do you eat yours?

You've got it in e-mails right? you remember it - I mean, it was only a couple of weeks back? What do you mean you forgot? what do you mean she's on holiday?

Discoverability - Pull vs Push

There're two ways you can spread information within your team - you can push it out to them, or leave it out there ready to be picked up whenever they want or need it, or maybe even when they least expect it. Both push and pull have their merits but I find that just sending e-mails out with links tends to get ignored in the deluge of all other work e-mails.

This is also true of mediums where time effects the findability. I'm thinking here mainly of 'streams' of content such as chat rooms and facebook wall style collaboration applications. Don't get me wrong, the publish date of content is incredibly important in such a fast moving industry but it's better placed as part of the header of the content, or as part of a historical 'version' of that content. Ordering unrelated content based only on the time written is the worst taxonomy. How far back does a viewer go? are they expected to read everything? is your stream poluted with unrelated or extremely transitory content?

Issue Tracking - we need to know when and how we fixed something

Day to day work is probably managed via some kind of task list/bug tracker. I say probably, I mean should be. It doesn't really matter which as long as it's searchable, identifiable (e.g. each task has a short unique url) and maintains its history (comments and status changes). It also needs to have complete visibility within the team. Segmenting access is just hiding potentially useful information from others. Each issue should clearly identify the problem or task followed by any information on what was considered during design or investigation and the final resolution. If possible include either a list of changed files or for extra brownie points have a system whereby issues are associated to actual source control commits.

Being able to search this is invaluable even if you're the one who fixed something. Your notes from the time are going to be far more detailed than your flakey memory. The nice thing about issue tracking knowledge is you can search based on the problem you know you fixed rather than the solution you can't remember.

Wiki

There are two types of information that you might want to store in a wiki. Project documentation, and general documentation. That is to say, meeting minutes, project documents/deliverables are quite different from tips and tricks or hosting details for a particular live site. At Headscape we used Confluence (as part of our JIRA install). In this setup we had wiki's per project that were used for day to day project management and a single central company wiki that contains: a page for each client including hosting and special information (such as accounts or third party tools used), pages for how to use or get up to speed with our internal tools and pages regarding the company such as phone lists.

To reiterate we don't want information stuck in people's heads or e-mail inboxes - and we certainly don't want to be one of those firms that have centralised access to everyones e-mail. No-one should want to be that guy.

If you research something why aren't you writing up your notes in a wiki (even if it's just a page title and a set of categorised links)? if you've figured out a process why can't you just send someone a link when they ask you about it? and seriously, why have you just saved these notes in a .txt file on your desktop?!

p.s. if your wiki pages have few cross-links in them you're doing it wrong... don't lose the potential for serendipitous knowledge sharing!

The Code

Comments

If Wiki's and bug trackers are considered 'par for the course' in a development firm so too is the idea of 'commenting the code'. To be honest I feel like I've gone through a similar process over time as Jeff Atwood has from 'Code tells you how, comments tell you why' through 'coding without comments' to 'learn to read the source luke'. The 'why' is definitely the most advantageous use of comments although the approach discussed by Jeff back in 2008 nails it in terms of the refactoring example removing the need for comments. Patronising comments suck and if a 'Find in all files' search for the words 'sorry' or 'hack' show double figures you should really start worrying about what people are using comments for.

Always keep in mind if you unintentionally or purposefully create an environment where people skip over the comments in your code because they're used to them being either pointless or out of date they're going to do that when/if it ever really matters too. You've just created the flashing banner ads of your codebase. Well done.

Common Code - Reusable libraries

This is far more useful as it is, by definition, the centralisation of other people's learning. If you don't have one please ask yourself why. I've written about this before but there really are many uses of a common code library outside of the oft told reuse/speed gains. Not only do I want to benefit by using my colleagues code I want to revisit their lessons by seeing their implementations, source code commits and potentially related wiki pages. I want to be performing code reviews of projects I don't work on so I can be kept up to speed with them and I want to be able to notice a pothole that I fell into in the past and save them the pain I had.

In my mind Common Code is the best back door route to knowledge sharing. You won't even consciously think you're part of a knowledge sharing solution you're just standing on a bridge built by your colleagues over all the crap they had to stand in.

Company Blogs

Personally I think company blogs are much maligned. The problem is they are all to often a marketing engine. Part of the point of the Headscape Barn site at the time was to try and avoid that feel. In my view a company blog should be more like a magazine with a collective of authors rather than a brochure pushing for sales. The big question then is why should your team blog for the company rather than just on their own sites? well.. for one: it shouldn't be to the exclusion of their own sites. The niche it sits in is being able to be directly about client work (which is often harder on a personal blog without discussion with the client themselves) and done on work time.

When deciding between a wiki page and a blog I like to think of blogs more as telling a story rather than listing cold hard facts.

Company blogs done in this way become a curated written history of project retrospectives.

Personal Blogs / Tweets

To be honest unless you've somehow broken into the big time the audience for your personal site probably goes (in descending popularity order) yourself, people you directly know, occasional google searchers who happen to hit one page. The great thing about them however, is a lot of the time they're something that employees already do (and should be encouraged to do so). You don't need someones job to be to curate and release a weekly 'interesting links' internal mail out - that was and is the twitter streams of your staff (who are also, probably already following each other).

Office setting

The simplest and most powerful knowledge sharing technique (and one I'm sure Marissa Mayer would agree with) is the office setting. Sitting near enough to people that you overhear their cries for help, eureka moments and sliding over on your wheelie chair when you hear "ooo that's interesting". That's not to say homeworking is anathema to knowledge sharing. Daily stand ups and cross team/cross project code reviews can all be achieved remotely.

My Ideal

I quite like the subtle, lead by example approaches of staff twitter streams and common code but the formality of wiki's and issue trackers allow for the full range of 'things I may need to know' on any given day being available without directly having to hassle someone to rack their brains.

The ideal tool is to replace google with a middle man that passes google results through but decorates them with results from your issue tracker, internal wiki and source control. This is a pure pull solution where you don't have to change your instinctive behaviour to jump to google when you hit an issue or have to make a decision.

Don't rely on people's memory, don't expect people to read things when you tell them to, don't silo information away just because it's a different team or project and don't create false settings for knowledge transfer - common code, blogs, code reviews, team rotation are all things you should be doing anyway for a variety of reasons - knowledge sharing being but one of them.

Other options

• A shared book library
• Attending hack days and conferences together
• Show and tells

Footnotes

1. If you're the guy who likes to hold on to info, safe in the knowledge that you will always be needed, remember, people will work around you. Your knowledge will be replaced (potentially shortly before you are)