Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
2  
Are you asking for too much documentation? "My basic guideline...about class diagram X...needed to know how your code works." I'd say, look at the code not the documentation. Documenting every class would be overkill at my place of employment. If we could just get a solid public API well documented, we'd be good. –  P.Brian.Mackey Oct 6 '11 at 18:36
    
the level of detail we are looking for is major/significant classes only and one or two paragraphs for each class describing its purpose and function in the overall module. Doesn't seem like a lot. Most SDS documents we have are only about 20 pages, and that includes all diagrams (which take at least 25% of space), TOC, cover page... –  DXM Oct 6 '11 at 18:54
2  
"the level of detail we are looking for is..." How is this tested? How can folks be sure that they are meeting this goal? Is this an official sprint deliverable? If it's not a sprint deliverable, why would anyone do it at all? If it is a sprint deliverable, what's the acceptance criteria for it? [I'm not trying to dismiss your question.] –  S.Lott Oct 6 '11 at 19:10
1  
@S.Lott - It 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. After 2 reviews/rewrites of the same document and it still not meeting the minimum, what do you do? go for the third one? or give up? and obviously after second review cycle the sprint is over, so now it spills over into the next one. –  DXM Oct 6 '11 at 19:22
    
@DXM: "After 2 reviews/rewrites of the same document and it still not meeting the minimum, what do you do?" "...sprint is over, so now it spills over into the next one". Correct. I'm afraid I don't see the problem. That's what's supposed to happen, right? What's wrong or broken about this? [I'm not trying to dismiss your question. I just don't understand it.] It would help to update the question to clarify this process issue. –  S.Lott Oct 6 '11 at 19:27
show 2 more comments

4 Answers

up vote 5 down vote accepted

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 members of the team actually do find the documentation useful, then 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 there are problems that 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 just 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.

share|improve this answer
    
Thomas, I completely agree that putting responsibility in the hands one developer is dangerous and anti-agile. What if you have more than one developer, but taking out of the hands of "certain" ones. So the question is if different people have different skills/strengths/competencies, should they still be given completely equal responsibilities in the team? And don't get me wrong, I encourage and help anyone that wants to take on more things, but it seems certain people just don't want to do those things in the first place. –  DXM Oct 6 '11 at 19:18
    
@DXM Find out why they don't want to do those things, especially if they find the existance of the documents helpful. One of the things that the agile methods are really good at is continuous improvements through your retrospectives after each iteration. Having people who are fighting the process and artifacts is only going to be a hinderance to the rest of the team, so try to figure out what the problem is and deal with it appropriately. –  Thomas Owens Oct 6 '11 at 19:45
add comment

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?

share|improve this answer
    
see my amendment, contradiction is because we have "core" team and we have people who are coming and going. We also have new people who are "core" but they don't feel that way yet. Unfortunately, we can't start with clean slate and have all agile discussions every time a team member is added/removed from the team, so some entered and they were told this is how we do things. –  DXM Oct 6 '11 at 19:28
add comment

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.

share|improve this answer
add comment

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.
share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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