Document Your Air, Food, and Water

Editor's note: The following is a guest post by Travis Illig. Travis Illig is a .NET developer who enjoys the art of solving problems with technology. He is currently 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 http://www.paraesthesia.com.

• If you'd like to submit your own guest post, contact me.

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 is the source code repository?
• Which tools need to be installed on your developer environment?
• What are 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 is the task branch pattern in the repository?
• Where is the continuous integration server?
• Are there any specific development methodologies that should be followed?

...And so on. 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 actually documented anywhere. It's "tribal knowledge." People just sort of "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 actually know? Or is there a slightly different understanding of how things work from person to person? And what about new team members?

It's a good idea to document your air, food, and water in a central location that's accessible to everyone. Keep sort of a "team FAQ" that has the answers to all of 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 that "quick questions" causing team members to task switch are actually not as "free" as one might think. If there's a place that folks can go to answer simple questions, it reduces context switches, particularly when there are newer members on the team.
• Give new team members confidence in the team. Last time you joined a team, how was the experience? Did it seem a little jarring or was it really smooth? When you're new to a team it's like meeting a person for the first time... and you only get one chance for 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?
• Add 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 it?

1. Find a location. Find a central place on your company's network that 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.
2. Document as you get asked questions. As people have questions about how the team works - where the source code is, etc. - 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.
3. 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 that team member was responsible for that no one else really knows about.
4. 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 will 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.
5. Update as changes occur. As changes are made in the way the team works, update the document to reflect them. There shouldn't be so much information there that it's overwhelming to maintain, but the doc does need to be a living entity, just as your team is.

Make sure to keep your document fairly lightweight and easy to maintain. If it's too thick or complex, if information is repeated in multiple places throughout, people will skip updating it and eventually it will become stale. You don't want that - you want it to be easy so when it's time to update, it's simple, simple, simple.

It doesn't take much and it pays off in spades. Why not start today?

Comments

[Jason Dentler]

One of my previous jobs had a document like this. I was able to release a working module by day 4. At my other jobs, it's taken a week or more just to get a functional dev box, access to the repository (if they even had one), and a successful build of the current source.

[Harry]

Not trying to pick up a fight. Wouldn't it taking too much time to 'maintain' these documents? Especially, when the process changes quite often. If we do maintain the documents, what media from your experience work best? Wiki? Blog?

[Travis Illig]

As mentioned, the idea is to find that balance between "too much documentation that's far too much to maintain" and "so little documentation that it's not helpful." It's easy to fall into the trap of trying to capture everything in this document, and that's when it does become too much to maintain. This should be more like a cheat sheet that you could hand to someone - a one-pager that people can look at and become productive. Think about what the absolute minimum is that you need to know to get things going.

For example, rather than an in-depth detailed explanation of every nuance of the agile development process you're following, you might just have something like "The team follows a slight variation on the Scrum process. Standup meetings are at 9:00a every morning." The down-and-dirty details aren't really required for someone to get going and become productive. Plus, if more information is needed (or desired), maybe a separate document could be created and referenced by the "air, food, and water" document.

If the process changes so frequently that it's painful to maintain a very thin document explaining the process like that, it may be time to investigate why the process changes so frequently.

For our document, we use a wiki and it works wonderfully. It's easy to update, it's centrally located, and it's accessible by anyone. Added bonus - you can see the change history and potentially use that data to ascertain if things do, truly, change really often.