RSS Feed

Latest Entries

First time here?


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

  • 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?




Immediate and delayed satisfaction in software development

All our lives we're told a mantra that keeps repeating itself. We hear it as children when we want an ice cream, and we hear it as adults when we want that brand new car, or that holiday vacation:

Have some patience

But in the software world - things become a bit chaotic. Your boos wants things done now. The customer wants things done now. Not later, not tomorrow. 

So what do we tell our customer?

Have some patience (and these changes you wanted tomorrow can wait 6 months)

What do we tell our boss, though?

Um, OK. I think we might be able to do that!

That's right. We succumb to our own feelings that we want to be able to do anything quickly, so we say we will (but we never do, do we?)

Why don't we ever get to that point where things can be done now in software? 

There's a simple answer:

We are letting ourselves be patient with our development process and tools. We allow waste of time when we build the things that we promised our boss we'll deliver now.


  • When we want to release a product we get told that it will take 3 weeks to make sure everything works - so what do we tell ourselves?


Have patience


  • When our machine has bluescreened for the 3rd time today, our source control takes 10 minutes to get the latest version of 2 files and our team keeps finding bugs manually by debugging - we say one thing to ourselves:


Have patience

Somehow, we have convinced ourselves that in software, like real like, there are certain things you must take for granted (death and taxes). things you can't fight, so you shouldn't even try.

We fail to realize that in software, like in The Matrix, rules can be bent. Things that take a long time can be automated. Things that are hard to do can be made easier with tools (or by removing tooling!)


People who cannot live with delayed satisfaction in the real world, suffer from the environment, since some things, they learn, are simply going to have to wait. they may feel more negative about things, they may seem pushy, abrasive and ill mannered, but they are just troubled by a built in lack of what psychologists call "Optimal Frustration" - the ability to wait for what you really want, and still feel OK about it.

Funnily enough, in Software, those same people can be tremendously successful team lead, due to that exact lack of ability to endure delayed satisfaction. Thos eare the people that keeps asking qustions like these:


  1. "Why can't I have a working build with installer at the push of a damn button?"
  2. "Is there a reason you invited me to this meeting? you're wasting my time"
  3. "Why do I have to login to my computer to see how the team is doing?"
  4. "WHy are we still doing this manually?"


and so on.

eventually, what these people drive is the ability for an organization to not delay its satisfactions - when they want to release something, they can do it on a whim. When they want to fix a bug and send a patch to a customer, they can do it without a hassle.

if they really want to, they can fix something that just came in as high priority in the middle of an iteration and not even flinch.




The three stages of learning team leadership

or anything else, for that matter: Shu-Ha-Ri :

  • Practices
  • Principles
  • Values

*see related to this:




This blog is right now at the "Practices" stage: Lots of "Do this" and "Don't do that", with just a little "Principles" thrown into the mix.

The values? Those take time to develop. It's those "Values" that will make people write comments on these blog posts that don't agree with the post's sentiment, as they talk about a practice, instead of a value (when they coexist nicely).

For example, on my "Own your team and territory" post, i got quite a few comments that say "You must let the team learn how to do these things etc, which is more in terms of a "value" system.

But in the context of a "Learn initial practices" system, it does make sense, since that person has not yet masterd and feels comfortable with the accompanying princinples and values attached. when they will (and they will eventually) they can (and should!) start questioning their tactics - for at this point, in this context, those initial practices are the right thing:

= they are easy to follow

= they will bring some peace to the team and the lead so they can start focusing on more principles

= the values will have to be "earned" during time.


Test Driven Development is the same way:


  1. you start out with the 3 rules of TDD (practices - failing test, code to pass, refactor)
  2. you learn why they matter (the principles - test the test, think small, have partial work etc..)
  3. you learn the values of a SOLID designed system, and the ability to take and get quick feedback, and start aiming how and when you use TDD within those values.



One-Liners a new team lead should and shouldn't read

Alistair's blog\wiki has a set of specific one liners from programmers - to newly minted team leads.

The whole list is here.

My 3 favorites were:


Whatever their job is, help them be better at it.


You are now a junior person in a brand new career that you never were trained for – and keep in mind that the medium you are working in is PEOPLE.


People will bring you their issues with teammates – it will help to give your people some training in how to deal with those issues themselves.

Notice that they all talk about the idea that you are working with people, and that driving people to be better, and caching them to solve their own problems is important.


Now, here are a couple that I didn't like:

YOU ARE THE ABSTRACTION LAYER – you provide the Bubble of Happiness.

Only to a certain point. Once your team is ready to face challenges, it's OK, and even welcome to start letting them deal with real world stuff  - how do they handle outside interference? what happens when a higherup asks for a small feature really quickly? 

A mature agiel team should be able to handle these, but don't try to let them handle it if you're all still learning the territory. It's OK to have an "incubator" where the team lead only gets all the "heat" from the outside, but that doesn't mean that a team can't go and face their real customer and see what their all about.


Generating Internal vs. commercial value

Alistair writes about something which I've only thought about in small glimpses, moving on to my daily business: 

One of the basic ideas behind lean development is that you narrow the amount of process that is done at the company to only those things that add value. Continually trying to remove "waste" from your process is a key learning.

The big question is "What is value".

If your manager is big into "lean" they can say

"Don't work on refactoring - it doesn't add any value to the customer"

"Don't work on making the build faster - there is no customer value in that"

but we all know there certainly is.

It's internal value - that makes sure things are kept at the highest quality.

In "Lean Software Development" the toyota way is introduced. What I've gleaned from it, among other things, is that you "remove waste - but keep the things you cannot do without"

It is those things that make "internal value":


  • a constantly trimmed and refactored build process
  • constant refactoring of code base
  • code churning for readability
  • teaching people
  • coaching about problems
  • having fun at work


There is indeed internal value in these things, but as alistair says = there is the danger of saying that anything brings internal value. 

For an agile team - it is those things "you can't do without" that you take from more specific techniques like TDD, XP, Continues automation etc...