Why Enterprises Crave Documentation Artifacts

Episode 22

July 13, 2011




The Agile Weekly Crew discuss reasons why enterprises seem so hungry for documentation artifacts.

Episode Notes

Chris Coneybeer, Roy vandeWater, Derek Neighbors and Drew LeSueur discuss reasons why enterprises seem so hungry for documentation artifacts.



Cover your ass

Avoiding conflict

Turn over safety blanket


Documentation isn’t bad

Communication trumps documentation

Trust helps prevent need for documentation

Siloing / Lack of cross functionality

Team members are people not widgets

Limiting communication pathways

Documentation as a wall to avoid interaction


Chris Coneybeer:  Hello again. Welcome to another addition of ScrumCast. I’m Chris Coneybeer.

Roy van de Water:  I’m Roy van de Water.

Derek Neighbors:  I’m Derek Neighbors.

Drew LeSueur:  I’m Drew LeSueur.

Chris:  Today, trying to go through topics and something we thought about was large corporations and the need for artifacts during sprints and during projects using agile methods. I’ve worked in several large corporations where have been beaten under with pages and pages of requirements, tracking, and all kinds of other documents or artifacts needed for managing a project.

I want to get the group’s feedback on what your feelings are and also with some of the people here that have been working off side at other teams. Have you come across these issues? How have you tried to deal with that in adopting agile and scrum techniques?

Roy:  I think part of it with the documents ‑‑ what is the real value that they are trying to get out of these documents? What are they trying to accomplish by having these documents as part of their process?

Chris:  I think traditionally what I’ve seen with a documents is that they have been put in place to try to enforce processes, when other ways weren’t working for making sure that these processes were happening ‑‑ such as release management, and making sure the security have happened, code checks have happened, just sign off.

People weren’t doing their jobs. People weren’t being held accountable, and they weren’t doing what they said they were going to do. Documentation and processes were put in place to try to clean that up.

Roy:  Would you say that most of these documents or most of these artifacts are documentation of accountability?

Chris:  I think accountability, but also user requirements. I’ve seen some rather large user requirement documents that if you had interactions, if you had conversations with a business owner and the stakeholders, you could do a lot better job in understanding instead of just throwing a document over the wall, and then waiting for something to come back over.

Derek:  It’s right, because I used to think of the desire to over document. I think we can all agree Agile is not about documentation. But I used to think it was all about cover your ass ‑‑ meaning that the reason that most of the managers I saw that were demanding documentation as a team member, I always felt that they were doing it because they didn’t trust the team.

They wanted some artifact to prove that if their boss yelled at them, they could say, “Well, look. We documented all this. The documentation has been for a long time, and nobody commented on it. How would we know?” But the other night, I was re‑reading Lisa Atkins’ “Coaching Agile Teams” book. She said something in it that made me just now think about documentation.

She said when she was a typical project manager before adopting Agile, one of the things that she said is she didn’t ever have to deal with conflict. The reason she’d never had to deal with conflict is because the way that the processes were built. Everybody was siloed. You were only on a project for a certain amount of time.

If I am the manager of a testing team, I’m only on the testing project for a certain amount of time. There are all sorts of conflict in whatever brewing up it doesn’t really matter, because in four weeks we’re not on this project any more. All the conflicts we had with other people were gone.

I think this was one of the key reasons big companies really want documentation, is they are so siloed. They play pass the baton so much, that they’re definitely afraid of it. It’s almost like having turnover every four to six weeks inside of a company. If you could think about your entire team leaving and another team picking up where you left off, that’s really scary.

The best way to combat that is why I want all sorts of documentation. When I’m the new guy coming in, I’ve got my cheat sheet to go back to if I get confused. To me, is this part of the problem with big organizations? Is it they’re not fluid enough. They’re not cross‑functional enough. It incurs the desire to have documentation to cover up for that.

Roy:  I think that’s a really great point. Obviously, there’s less of a need for as extensive documentation when you’re working in a more open environment, where the team communicates verbally, primarily. I also really think the comment, or the phrase, or the idea that the main artifacts should be the code and the tests, is really powerful.

What actually is happening? The documentation can say whatever. It can become outdated. But the code and the tests that pass are, actually, real concrete documentation, and commit histories as well. I think in an environment where you’re more open, where you’re not siloed, where there’s more of verbal communication, and where you have good code and good tests then there’s a lot less need for extensive documentation that is probably not read very much, anyway.

Chris:  The one thing I throw out there is that in regard to this documentation conversation. I don’t want people to get confused and say that we’re trying to say throw out all documentation, because there’s still going to be some documentation that’s needed. You’re going to have compliancy issues. You are going to have maybe general architectural diagrams for a high system level understanding. What I have seen, though, is that since I have been at Integrum I have learned communication.

Communication is everything and team ownership of code is everything. That makes a big difference and what I have seen in corporations is that they are replacing communication with documentation. That is where, Derek, maybe the reason some of this turnover is happening is because there is no communication. Who is happy on a team when you are not communicating with anybody? They don’t realize it and maybe that is why people will get upset at what they are doing.

How do we try to replace communication? Replace that documentation that is being used as communication that we are used to in the projects that we manage?

Roy:  Part of what Derek initially stated where you had previously believed that it is a lot about trust. I think a lot of that still is true, a lot of is about trust, and that if you have a team that is consistently underperforming and whether it be because they have only been on the project for two or three weeks, because everyone is on the project only two or three weeks at a time.

If people stay on a project for longer and start performing and start doing well, I think that their managers will find less of a need to require documentation of them. Because they know that this team is going to do what they say they are going to do, regardless of whether or not they fill out the whatever report. Also as far are teams switching out really frequently, what is the primary reason for that?

Derek:  I think it is because everybody is specialized. If I am the enterprise architect, I am only needed really at the beginning of the project full‑time, and then after that you just consult me if you feel that there is a change in architecture.

If I am the Q and A team, and you really consider a story done when it is coded, not when it has gone through full Q and A, I am looking at the project in a much different time than everybody else. I need all sorts of artifacts to come along with me, because you are on another project. As a developer you are working on another project potentially by the time I am doing a large portion of the QA, or the enterprise architect is now on another project by the time it gets to it.

I think that there is something to be said for communication pathways. I think large companies have larger teams, which means it is harder to communicate face‑to‑face or person‑to‑person. It is easier to say we need to write that down so that anybody on the team can have access to that even when we are on the same project.

But when I think you add in the silos and not being cross‑functional, to me, it really comes down to people are treated like resources instead of like people. Managers treat everybody like a completely interchangeable widget that they are just pushing and plugging, so it is really easy to say, “I really like the work that Roy is doing and I need Roy this week, so I am going to pull him, pull that widget out and plug him into this other product.”

Now all your knowledge is gone, and because now you are on another team, it is no longer culturally acceptable for everybody on your old team to communicate with you to ask you information.

If you didn’t leave a litany of artifacts and you hadn’t been communicating with that team, all of your knowledge is now gone. The way managers try to protect themselves from that, I believe, is they want people to document absolutely everything so that they are guarded. If their resources get taken away, they’ve got a backup plan or a transitional plan to bring on new resources.

Chris:  That goes so much back to silos.

Drew:  Yes, I agree as well. Even if there is a situation, like you were saying, how somebody is just kind of plug and play like a widget out from one team to another,