Invisible Member

A new developer shows up to a team. They are eager to contribute and start writing code but have a lot of questions. Where is the source code? How do I set up my environment? How do I build the software? What is the development process here? Where do I look in the code to get an idea of where to start?

The rest of the team is busy, and try to get the new developer to self-serve by sending links to some documentation. Chances are the documentation helps with only a few questions, and certainly adds more. The documentation describes things that aren’t accurate anymore. The new developer hits a wall again in their journey to contribute.

Eventually, they get the help they need and someone says, “We should update the documentation.”

Teams and organizations struggle with a statement in the Agile Manifesto that reads, “Working software over comprehensive documentation.” I want to outline a straightforward strategy for documentation that is minimal and helps new developers and visitors who come to the team with questions.

I call it the invisible member.

Invisible Member

The idea is simple. Pretend there is an invisible member of the development team. This member cannot join meetings. They cannot call-in. They can only be contacted reliably through written mechanisms.

Consider a Daily Scrum with the invisible member strategy. The team meets and has a perfect 15-minute Daily Scrum. They know that they need to help their invisible member. Someone writes a small memo with the highlights and impediments wherever this invisible member knows to look.

For planning the same idea applies. The team goes into planning their next bit of valuable software. The invisible member wasn’t there, so how do we write a note about what was decided. The team again writes a simple note describing what the goals of the sprint are and any major non-obvious decisions. The plan of the sprint is likely recorded, so very little needs to be added regarding the plan. Maybe the team even decides to record important decisions in their tracking tool so the invisible member can understand what the pertinent information is.

As the team develops their code they know that there is someone who may be able to read the code but may not know the intent of it. They add some documentation for anything remotely non-obvious declaring the intent of the code. When they alter the system in a way that would impact the invisible members’ development they update the documentation that the invisible member would use to update their environment accordingly.

The team has a review and the invisible member would love to know what the feedback is and what the decisions were based on that. Someone writes a small note of that and keeps it puts it in the repository.

Retrospectives get the same treatment. The invisible member will never know what they discussed but would love to know what insight the team had and what they decided to do to improve. The invisible member wants to participate in whatever the team decided to improve. A note is written that highlights the insights the team had and what they decided to do.

The Visible Member

The invisible member strategy seems heavy. There are small traces of documentation left behind consistently when trying to help this pretend member stay informed. Practically speaking each of these documentation moments are going to be a few sentences per meeting. After all, the invisible member is a competent member, so they need the main highlights, some context, and the decisions.

The context that is provided can be quite small as there is a common thread that emerges through the numerous updates. The highlights help add context to the decisions without troubling them with the debate it took to get there. Maybe the invisible member would want to know how the group arrived at a certain conclusion, but there is enough of a thread of information that they can accept it.

Someday the invisible member will be a new member. Someone that shows up for the first time in the flesh. They’ll have a lot of questions. The team will be busy, so they’ll point the visible member at the documentation.

The documentation that was written the entire time to help a member that didn’t exist until today.