Agile development and documentation update

Asked

Viewed 403 times

8

Taking into account the second premise of the agile manifesto:

“Software in operation more than comprehensive documentation"

According to the agile practices, Scrum, XP, etc..., if during development, after having done the UML design of the classes, we verify the need to create a new attribute for one of the classes we should program the attribute in our class and database after and update the UML? Or we leave the UML design behind and continue planning iterations?

Remembering that agile methodologies do not discard documentation, but I would like to know to what extent we work together with it.

software-engineering uml documentation scrum

3 answers

8

The point is...

When your team meets or you discuss some functionality with a fellow developer, you use the diagrams?

In case affirmative, then the use must be everyday, therefore is rewarding the work of keeping the documentation up to date.

In case negative, probably the diagrams were made only for an initial understanding or to fulfill a customer or management expectation, so it’s not worth it, because work is more than the benefit earned.

Considerations

If the diagram source file is versioned together with the source code, then it is easy for any team member to update the diagram and Sincronize the project with SCM.

On the other hand, if the team usually works with printed documents, simply scratch the document in pencil and it will be enough to use in the next sprints (provided, of course, that no one plays basketball with the papers and a waste basket).

UML diagrams need not be a 100% accurate reflection of the code. In many cases, I avoid putting attributes in classes to avoid compromising the internal structure.

But what often happens is to use UML to represent the system’s database model. I don’t agree with that very much. There are more suitable tools that allow to make an MER (Entity-Relationship Model) and already synchronize the diagram with the database.

1

In the concept of "agile" development, documentation is a mere supporting factor in the process (user story is a great example).

If you are in "agile" the idea is that the documentation is collaborative, that is, it will grow according to the need and collaboration of all after team interactions (Daily Scrum or sprint planing for example).

The important thing is to deliver value to the customer. If the documentation is an artifact to be delivered as well, fatally you will have to update it, but not necessarily at the exact time a change was identified.

If the change will impact the next sprints, then it’s interesting that you update the documentation.

Now, if the documentation is not a deliverable artifact and if the changes do not match what is yet to be developed, I suggest taking it only as a lesson learned.

Remember that the focus on agile is to deliver value to the customer. So they don’t address documentation, although the documentation may be a value-generating deliverable.

Make your own judgment.

1

The easiest (and cheapest) way would be to make the changes in the classes (software in operation first) and then reverse engineer it to generate class diagrams and the like. There are several tools in the market that do this for you.

I think it is worth pointing something out here for reflection that has already been described in several articles, which UML is not documentation.

  • 1

    Despite the title of the cited article (I don’t have the full article), none of the sources (Fowler, Ambler) suggests that UML is not documentation. On the contrary: Again the UML is Useful here, providing the Diagrams are Selective to help Communication.

  • No doubt it helps communicate, but it does not imply that it is documentation. This is described in the linked article.

  • 2

    What I am saying is that the sources that the linked article cites do not prove the past idea, nor does the author provide an appropriate definition of documentation. In fact, the standard definition of documentation according to the main authors of Software Engineering involves precisely the communicating, then either the author wanted to be somewhat controversial, or he used an alternative definition of documentation.

Browser other questions tagged software-engineering uml documentation scrum

You are not signed in. Login or sign up in order to post.