Who should be responsible for writing/updating design specifications in an agile team

Question

I work as part of a scrum-like Agile team and a while ago, one thing we identified that the team should do is maintain good set of design documents for our code base. Because we are agile and do have good amount of discussion and communications, our designs are kept at a high level and are generally used for describing general layout of modules, including main classes and some of their interactions and. We also found them useful for discussion starting points since and also for reminding people that design needs to be considered before you jump into code.

So far, it was expected that everyone will update design specs on as needed basis. Design leads for each team are responsible for giving people advice on design in general, on what to update in the SDSs and also for reviewing the specs to make sure everything stays consistent.

The issue I'm seeing is that while everyone, especially new members find design specs very helpful when learning new components or even going back to components they haven't touched for a while, most people only update the docs for the sake of updating them (i.e. they are told they must do it and so they do it). So that we end up with one-liner descriptions which sometimes aren't even full sentences and when I tell them this needs to be updated and filled in, they add more but again, only because they are told. So now one-liners become 1.5 lines and there's still nothing helpful written down.

Obviously different team member skills/strengths will be different. So the question is, should certain team members on an agile team simply not be responsible for design and be reduced to just a coder? Or should it be design leads role to go back to those team members and make them rewrite the specs as many times as necessary (and this is really becoming painful) until they pick up enough skills to produce what's expected?

My basic guideline that I suggest to everyone: if you were sitting in a meeting or making a presentation about class diagram X, what would you say if your audience needed to know how your code works. Instead, half the time they simply restate what I can already see in the class diagram. "Class X implements interface Y". That would be entire class description.

Amendment: I work for a large corporation with a very healthy appetite for outsourcing/contracting. The team I'm on has permanent members, it also has permanent members who are very new to the team (from recent merger). And we have contractors from India and Poland who will most likely be reassigned to other project after the current release. So different members have different buy-in at this point. Documentation is definitely important to those of us that have been on the project in the last release and will be on the project in the next release.

Answer 1

I'm not sure if you have read it, but I recommend reading Scott Ambler's article on Agile/Lean Documentation.

The issue I'm seeing is that while everyone, especially new members find design specs very helpful when learning new components or even going back to components they haven't touched for a while, most people only update the docs for the sake of updating them (i.e. they are told they must do it and so they do it).

That seems somewhat contradictory. If the team members actually do find the documentation useful, that should be a motivating factor in keeping them up-to-date. If your development team isn't actively updating the documentation to capture decisions, perhaps some problems need to be addressed. Is the documentation relevant? Does the current format of the document facilitate communication? Are you trying to produce documentation that is too good or too formalized for the purpose?

So the question is, should certain team members on an agile team simply not be responsible for design and be reduced to just a coder? Or should it be design leads role to go back to those team members and make them rewrite the specs as many times as necessary (and this is really becoming painful) until they pick up enough skills to produce what's expected?

Delegating design documentation updates to a single team member, in my opinion, goes against agile. Part of the point of agile is to reduce risk, and you do this by spreading responsibility around. Just like no one owns code, no one individual owns documents either. Rather than have team members rewrite specs, try something like pair programming to teach these people how to write better documentation or institute reviews on produced documents to provide appropriate feedback.

Answer 2

There's a saying one of my professors in college liked to throw around "find the contradiction between what people say is important to them and what they actually do and you'll understand them perfectly".

So the team says they like documentation, but don't actually create it when appropriate? What they value is convenience. It is much easier to read well written documentation than to try and tear in and understand code. It is also a lot easier to ignore updating documentation than to do it. So where ever it is that you keep your list of team values strike out documentation (if you even put it on there) and write convenience big bold letters.

So now when discussing stories and creating tasks, the team will have to address the convenience factors. Is this something that should be written down for the future? Will the value it might give down the road balance out against what it costs now?

Answer 3

I believe the way you stated your question already contains the answer. You're talking about the type of documentation that relates to only one type of work -- designing and implementing software code -- so the people responsible for it should be the ones who carry out this type of work: the software developers. Agile or not.

I do find a contradiction in your question and resolving it may help. One one hand you say, " one thing we identified that the team should do", but on the other hand you say the very same team who "identified it" are now so reluctant and sloppy at maintaining these design documentation -- this may indicate that they didn't really buy into it.

I would ask, who identified this documentation activity as a need? Did the team buy into it? How exactly did they agree to carry it out? Revisit this topic and these questions in a retrospective.

Answer 4

Since you mention Agile, it would be natural if you experiment with different approaches and find out which works best for your team.

Given information provided so far you appear to be in a very good position for that:

It [design specs] is a deliverable, it is tracked in iteration and people are given tasks to both write specs and review specs. Acceptance criteria is team's consensus (with design lead having more weight) that the spec meets what's expected when the review is held...

We have a review meeting...

Above sounds as almost perfect tooling for collecting data and performing comparative analysis for various approaches. I would rather prefer to have QA verification as an acceptance criteria over team's consensus but even as is it feels good enough.

• A word of caution: before starting experimenting, one would better clarify with management their understanding of Agile - because, you know, sometimes they happen to have their own, quite a special way of looking at it.