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.

  • 1
    Fairly junior people could write good documentation too. Perhaps those who cannot write down technical stuff well cannot code well either. It might not be about years of experience.
    – Job
    Commented Oct 9, 2011 at 13:49
  • I did try to structure it as multiple factors: a x b x c... and there could be few more I didn't list. Let's say (b)=experience. There's still other factors that will determine the quality of output.
    – DXM
    Commented Oct 9, 2011 at 19:31
  • My unfinished thought: fire the incompetent ones and then you do not need to worry so much about any factors. I beet 19 yo interns at FogBugz can write decent documentation.
    – Job
    Commented Oct 9, 2011 at 23:45
  • What is your relation to the team? As outsider/stakeholder, I would align with the team on the documentation requirement, document that in the DefinitionOfDone and let the team self-organize. Commented Oct 11, 2021 at 6:21
  • Great question, @KrisVanBael! Unfortunately I don't remember seeing how I asked this question 2 days, 4 companies and 10 years ago :(
    – DXM
    Commented Oct 11, 2021 at 21:01

5 Answers 5


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.

  • while you provided good general advice, you have completely avoided the only question I'm trying to ask. Would you agree that on a typical team, there's a significant difference in skill/knowledge between engineers? If yes, would you agree that those engineers given the same task of writing a design document would produce very different results? If yes, would you agree that documents written by engineers with better communications skills, better design skills and better knowledge of the product would produce better documentation? My question is one the best approach to handle this gap.
    – DXM
    Commented Oct 9, 2011 at 9:49
  • I also want to stay away from general theme of "review if you need documentation in the first place". Our team knows that we need them. We had this discussion. Now my question is exactly what you see in the original post.
    – DXM
    Commented Oct 9, 2011 at 9:53
  • The question is tagged "agile", so I gave you an agile answer. It's impossible to answer yes or no categorically because each team is different. So let them deal with it while aggressively focus on eliminating waste. That is my answer, sorry to disappoint you. :) Commented Oct 9, 2011 at 10:05


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).


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.


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.


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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.