Pairing is great for knowledge transfer. With a reasonably sized 3 pair project, you can completely avoid code reviews, training sessions, tutorials, or any other means of teaching a developer how something works. I had a good amount of time on a 6 pair project with a ~15 developer-year code base and felt a lot of pain with poor knowledge transfer during that time. Pairing just wasn’t enough. We experimented with a few additional ideas during that time and found four that I would certainly use again on any future large project. The parking lot, a pairing whiteboard, frequent technical retros, and developer documentation. If your project is big enough, you might want to give these a shot.
Parking Lot
This has been used on a number of other Pivotal projects, but worth reinforcing. As you are working through the day, if you ever create something other developers should use in the future (a helper method, or useful mixin, or new jasmine matcher, etc), write it on a whiteboard. This goes double if there is something old that developers should have been using but didn’t know about. I’ve found I typically write one thing per day. At the beginning of standup (or perhaps before standup, with only the devs), go over all of the items on the whiteboard. The same info could be contained in the standup itself, but there is a lot more useful info transferred this way in practice.
Cost: A few minutes a day, less than the cost of standup. The ask ticket for the whiteboard.
Pairing Whiteboard
Also taken from other projects. We found that if pair rotation is basically random, you have very little control over what you work on and therefore very little control over what parts of the code you know. We have every person’s name on a post-it note and write down every story that is carried over from the day before on a whiteboard with the owner’s post-it next to the story. This goes for stories that weren’t started the day before but clearly need to be started today. You then assign pairs based on who needs to learn what. You can also use the same mechanism to create power pairs if the situation calls for it, but that doesn’t help knowledge transfer.
Cost: Same as the parking lot, plus some post it notes.
Technical Retros
I used to think technical retros were only when the whole code base is about to fall apart or you need make a major infrastructure decision and want the whole team involved. Developers know how to solve technical problems and we don’t need meetings to do this. It turns out these retros are great for knowledge transfer. We only did this for a month or so before our team size was reduced for other reasons, but I’d recommend having technical retros on big teams once a week until you feel they aren’t helping and then dial back.
I have observed three mechanisms for this knowledge transfer. If someone has been working on a component they don’t understand, this will end up in the unhappy column and now everyone knows that component needs more explanation. If someone knows a component and thinks it should be changed, everyone else gets to listen in when the two people who actually understand it discuss it. Lastly, when people discuss changes to the infrastructure, it ends up including good explanation of how the current infrastructure works.
Cost: An hour-long meeting every week with the whole team is a lot. Only really worth it on large teams.
Developer Documentation
I’ve noticed we treat documentation at Pivotal the same way we treat code comments, lies waiting to happen. What is the point of writing down how some API is going to work when you already have tests describing the behavior and the API is just going to change next month? This may be true for low-level documentation, but we have drawn a lot of value from higher-level documentation, showing general code flow and including examples of how pieces fit together. We originally wrote the documentation because we are open source and needed to help out some third party devs, but it turned invaluable as a teaching resource. Our documentation is split into two parts, one with info on how the code works (here) and a second “DevOps Manual” with info on dealing with our development and testing setup. The DevOps manual is in a private repo.
Documentation writing was prioritized in tracker. There were many stories “Document X” that built things up over time. The stories were usually the result of action items from retros (technical or process) whenever a knowledge silo is identified. Many pages were written by a pair with one experienced person and one new person. This has the benefit of teaching the new person and forcing the experienced person to write something a new person can understand.
None of this addressed the ‘lies waiting to happen’ problem of documentation. This is why we go over it all with each new developer on the project. After a new developer has had some time to get their bearings, we put a chore in tracker to go over documentation with them (only if you are pairing with them of course). The other part of that chore is to fix anything that is wrong. This way every developer gets a baseline starting point and the documentation stays up to date.
Independent of knowledge transfer, the DevOps manual is pure gold. It pays for itself as soon as something like “The VM running my third party database for development ran out of hard drive space and corrupted the database” happens more than once. Whenever you fix something like that, even if you think it can’t possibly happen again, write it down. When you set up that VM in the first place, write that down too.
One last note on documentation, even if you don’t use actual documents, it helps a lot to document in the code itself. Detailed commit messages, detailed descriptions in tests, even code comments themselves occasionally.
Cost: We have probably spent at a pair week or two writing our docs. Maybe not worth it on a small project, but not too painful. The DevOps manual itself would still be valuable on most projects.
