Should all developers on a team have equal role/responsibility in writing and updating software design documents

Question

I've asked a very similar question few days ago, but because I presented too much of my company's current situation, most answers focused completely on something that I wasn't looking to answer. So I wanted to try again...

Given just about any agile team, you always have people with varied a) knowledge of the product b) experience in producing designs and c) general level of competence.

So let's say you take an agile team and using the factors (a), (b) and (c) above you come up with an overall score for each engineers (mental exercise only). Now we sort them in ascending order and get a continuous spectrum.

So the question I wanted to ask is this: Should every single person on this spectrum be given equal responsibility as it comes to writing/updating software design specifications?

I'm not talking about coming up with software design, in agile teams that is usually done by more than one person in a more collaborative setting. But at the end of the day, someone has to go back to his desk open their favorite (and company/team approved) document editor and type it all in.

The reason I ask this question is because it seems people on high end of the spectrum tend to produce documents which are more readable, concise but have exactly the information you would want in a design specification so that future people who read it have much more benefit. People on the opposite side of the spectrum tend to produce documents which are not nearly as useful or clear and a lot of times, even with several iterations of design reviews, their work doesn't seem nearly as helpful (so specs they produce become write only dumping ground that no one reads or trusts because of the way they are written).

I'm not proposing that the agile team be segregated and only certain individuals given certain roles that will never change. I'm asking... 1) what do you do in your teams with people who have vastly different (a)x(b)x(c) scores 2) Does it make sense to not give equal responsibility to everyone. Instead, give only smaller (or none) update tasks to those on the low end of the spectrum. But then work with these individuals by identifying (a), (b) and (c) factors that they'd need to improve and as those get improved give them more responsibility.

Personally, I'm not sold on one way or another, I'm just curious how other teams are dealing with this.

Answer 1

Writing documentation is a shared burden like everything else on an agile team.

Begin by asking your team what kind of documentation they really need, how much of it and how often it must be updated. Then coach them through that discussion keeping agile values in mind. Eventually they should agree and commit to something, and whatever they come up with is probably the correct answer in your case. It is not your place to tell them how they should do it.

It often turns out that the documentation is not used in practice and only exists because of company policies. If you find that you don't need all of it, most of the problem with writing documentation goes away. For instance, deriving knowledge from the code using comments, clean code and unit tests as specification helps a lot.

Answer 2

Yes

Let me answer with a counter-question: If there was a component of the system that was particularly suited to one developer's skillset, should the team's preference be that she is the only one that works on it? In an agile team, almost certainly not. One of the goals of the "agile process" is to share and distribute knowledge. If those that are bad at writing design docs don't get practice and feedback, how will they improve?

Build maintenance, writing code, compiling, design docs, debugging, testing are all parts of the software developer role in nearly every organization. If you have a long-term interest in investing in the members of your team then you should look at improving the weaker skills, possibly by pairing them with a mentor with a strength in that skill. It's difficult to improve without practice.

Whether or not design docs are important to an agile team is besides the point. If a developer cannot communicate a design well, then he can't communicate well. I've worked on teams where team members couldn't use svn. I've worked on teams where only one person knew how to format a config file. I personally think Microsoft Word is intentionally designed to work in direct opposition to the way I think about writing documents. It doesn't matter. If that's the tool my team uses, then I have to adapt to that environment to work effectively in a team. (That's not to say there aren't ways to change the environment, but that's a different discussion).

Answer 3

It is a good thing that you are considering documenting design specs. As you said, if writing is left to individuals, you will get varied levels of quality. One way to help raise the quality and value of this type of documentation is to design template(s) of what should be documented and good examples of what to include and not to include. Then have 1 senior person review the output (much like a code review but with fixed max. number of iterations). It is hard to get homogeneous output without doing this.

Also, please note that some technical people are not skilled in writing at all. Make sure you don't press those people for performing such tasks. If you have a system with large number of components, most people must help with the documentation. Tasking only few skilled ones will make their development output suffer.

Answer 4

There is no fixed recipe for documentation; like everything else, it highly depends on the people in a team and their personalities and abilities. Everybody can do their part, or one person can take the task to himself. Anything goes, really. I've had good results with tester writing most of the documentation, but it's maybe the best when an architect/project lead does the documentation. Each programmer doing his part can also work, but some programmers are really bad at this.

The question you should be asking is what's the best way to tackle the problem with your team, not how it should be done in an ideal world. Use people's strengths or strengthen people's abilities if they're bad at something, or even better, do both when you can.

Answer 5

Yes. The self-organizing aspect of agile teams allows the team members to determine who will do what; and the tactics of HOW the team will operate in order to get things done will vary from project to project.

Improving the strength and flexibility of any team will require:

• that junior members learn by doing, everything.
• that junior members recieve feedback/help that aids improvement
• that the team itself is satisfied with the outcomes, and adjusts their operating tactics when that is not the case