Chapter 15. Document your air, food, and water
Think about all of the things you need to know when you’re new to a team. There are a lot of things, right?
- Where’s the source code repository?
- Which tools need to be installed on your developer environment?
- What’re the steps to build the product?
- Is there a pattern for how the code is laid out in the repository?
- How are tasks tracked?
- What’s the task branch pattern in the repository?
- Where’s the continuous integration server?
- Are there any specific development methodologies that should be followed?
This is, from a peer mentoring perspective, the “air, food, and water” for the group.
It’s the stuff you need to know in order to basically get around. Many times, the answers to these questions aren’t documented anywhere. It’s “tribal knowledge.”
People “know” what needs to be done, and if you don’t know, you ask the group. That sort of approach might work well in a small group that doesn’t change a lot, but what about in a larger group?
Does everyone know? Or is there a slightly different understanding of how things work from person to person? And what about new team members?
Document basic team information
It’s a good idea to document your air, food, and water in a central location that’s accessible to everyone. Keep a “team FAQ” sheet that has the answers to all these questions, and make sure everyone knows where it is. It doesn’t have to be reams of heavy documentation, but it should contain enough to clearly answer the questions.
Why document?
Enable team members to help themselves
It’s generally understood[1] that “quick questions” that cause team members to task-switch are not as “free” as you might think.[2] Having a place that folks can go to answer simple questions reduces context switches, particularly when there are newer members on the team.
See Jeff Atwood’s “The Multitasking Myth,” Coding Horror, September 27, 2006, https://blog.codinghorror.com/the-multi-tasking-myth.
See Kermit Pattison’s “Worker, Interrupted: The Cost of Task Switching,” Fast Company, July 28, 2008, http://mng.bz/vU68.
Give new team members confidence in the team
The last time you joined a team, how was the experience? Did it seem a little jarring, or was it smooth? When you’re new to a team, it’s like meeting a person for the first time ... and you only get one chance to make a first impression. Wouldn’t it be nice to join a team and have the reassurance that there’s a plan and a simple document that lays out everything you need to know to get going? If you saw that, wouldn’t you gain a little confidence in the team?
Provide visibility into your team
If there are other people or teams in your company that are interested in seeing how you’re doing things, maybe to learn something from your team, having a document makes it easy for them to see how things are done and understand what they’re looking at.
How do you get started? How do you maintain this document?
Find a location, and tend the document
Find a central place on your company’s network where you can store the document such that everyone has access to it. Maybe it’s a wiki. Maybe it’s a SharePoint site. Maybe it’s a simple file share. As long as everyone has access to it, it’s perfect.
Document as questions arise
As people have questions about how the team works—where the source code is, and so on—refer them to the document. If the answer isn’t there, consider adding the answer to the document and providing the document to the person asking the question. Eventually you’ll have a document with the answers to the most frequently asked questions about the team.
Pass it by exiting team members
Team members come in, and team members move on. Before a team member moves on from the team, part of the knowledge transfer should be having them review the document and fill in applicable answers. There may be some things the team member was responsible for that no one else knows about.
Give it to new team members
When a new member comes on board, give them the document as a way to get them set up. It’ll quickly become apparent if the information on the document is incomplete. When incomplete/incorrect information is encountered, have the new team member work with the team to find out the correct information and update the document.
Update as changes occur
As changes are made in the way the team works, update the document to reflect them. There shouldn’t be an overwhelming amount of information to maintain, but the doc does need to be a living entity, like your team is.
Keep your document fairly lightweight and easy to maintain
If it’s too thick or complex, or if information’s repeated in multiple places throughout, people will skip updating the document and eventually it’ll become stale. You don’t want that—you want it to be easy when it’s time to update: simple, simple, simple.
It doesn’t take much, and it pays off in spades. Why not start today?
Roy’s analysis
One immediate value to this practice is that it can help reduce bus factors in your team.
I once had a team member who was the only person who knew how to clean up disk space on a build machine when it filled up. He used a special script he made a long time ago, and only he knew where it was located and how to run it. By documenting that stuff in a shared wiki, it was easy to then point people to the wiki page if and when it was needed, regardless of if he was there. Bus factors are huge risks to the team and any project you’re working on, and knowledge sharing in a safe place that’s easily accessible and searchable is a safety net preventing the risk that only one person possesses unique knowledge.
It’s possible that a lot of unforeseen work your team might be doing has the root cause that they’re reinventing the wheel, or not sharing information well enough. Creating a script to clean the disk when someone has already created such a script is wasteful.
Acting on this advice can prevent situations that risk your team devolving back into (or keep the team in) survival mode.
This advice might belong in the learning phase, because it might require time you need to handle getting out of survival mode.
TRAVIS ILLIG is a .NET developer who enjoys the art of solving problems with technology. He currently is a Senior Software Developer with Fiserv, working on next-generation online banking products. He holds a BS in Computer Science from Portland State University and is a Microsoft Certified Solutions Developer (MCSD) for .NET. Travis can be contacted through his blog at www.paraesthesia.com.