PM 2 go Praxis
Applied to software development, the notion of a Design Decision
Projektmanagement wird ein zunehmend wichtigerer
Erfolgsfaktor für Unternehmen im Wettbewerb. In
dieser Ausgabe von PM 2 go Standards lesen Sie die
praxisorientierten Kurzartikel aus dem Blog von Projekt
Management Beratung.
Fighting lack of documentatin in
agile software development
By Andreas Heilwagen on March 7th, 2011
During my last project, Fabian Kiss, a software developer who loves
agile and lean environments, worked on his master thesis. He says,
that in his daily work he is never tired of convincing a stakeholder
of the benefits attained by practicing sustainability throughout the
entire development lifecycle.. Now he has written his thesis and
here is a summary of his approach to support documentation in
agile software projects:
Design Decision Rationales in Agile
It’s common knowledge that maintenance and further
development of existing software products constitute most of
the work in daily software development. So it is essential for
software developers to understand from the source code what has
been implemented – and particularly how that has been done.
Eventually they have to understand the structure of the code and
its behavior in the context of the application domain. This cognitive
task is well-known in academia as Program Understanding or
Program Comprehension since the late 70s.
Importance of Program Comprehension in Agile
It might not be suggesting to consider such academic stuff
originating from the Jurassic era of computing in contemporary
agile software development. However, it is evident that the
common agile practice of continuous code refactoring increases the
need for Program Comprehension as the code has to be understood
again and again. Certainly, you can count on the favored face-
to-face communication with fellow developers and, further, with
non-developer stakeholders. But let’s be honest, there is always a
certain knowledge decay that necessitates a developer to “consult”
the code. One more time, Program Comprehension is involved.
Consequently, it is advisable to have a documentation that supports
more or less directly the Program Comprehension of a developer –
additionally to the concept “the code is the documentation”. Taking
account of the agile value ”working software over comprehensive
documentation” makes it clear that such a documentation has to
induce a benefit discernible to the customer – to justify the effort of
documenting when considering the YAGNI principle. A challenging
endeavor as we deal with a matter that is apparently related solely
to programming.
Design Decision Rationales as a documentation approach
A possible solution could be a documentation based on Design
Decision Rationales, originally known from the discipline of system
development. By extracting the essence from its various definitions
in literature, you can say that a Design Decision Rationale states
the reasons behind a decision that was made during the design of
a software system. This in order to clarify the decision. For that
purpose, it can also argue why alternative design options have been
rejected.
Rationale can be extended: It could also deal with a decision which
was made during the implementation. Obviously, that would be
helpful for a developer in respect of Program Comprehension. Re-
considering the exemplified refactoring, an appropriate rationale
could justify, for example, why an obfuscating piece of the code was
implemented like that or why it was not refactored subsequently.
Possibly because a refactoring would simply have been too costly
for that piece of code, while the development has been considered
as sufficiently agile despite this distinct violation of a common agile
practice.
Are agile values and principles met?
Similar documentation approaches based on Design Decision
Rationales were proposed in the context of agile software
development in research papers – with a focus on a lightweight
producing of the documentation as well as on a supposed
facilitation of decision making in teams through it. But also
literature for practitioners advises the idea of documenting with
Design Decision Rationales: Andreas Rüping explicitly addressed
that idea in his pattern collection for documenting in Agile by a
pattern named – not surprisingly – ”Design Rationale”. Robert C.
Martin as one of the authors of the Agile Manifesto addressed it
likewise explicitly in his Agile book when reflecting on the agile
value ”working software over comprehensive documentation”.
So why not considering this idea properly as an agile
practice? Then, the documentation should base on informally
represented Design Decision Rationales: There exists no common
representation of them, but recommendable is a brief text written
in natural language – freely adapted from the form of user stories.
Here is a fictive example about the implementation of a credentials
verification in a typical login scenario:
password is passed together with its original set date to determine
internal encryption
passwords set after 2008-10-01 have been encrypted in DB with
SHA-2, not anymore with MD5
Never neglect customer satisfaction!
When the Program Comprehension of a developer is supported
by documentation, a consequential benefit could be the improved
quality of the resulting software product. Without doubt this
would be a benefit for the customer. However, it is questionable
whether that benefit is “direct” enough for the customer:
Supporting Program Comprehension does not directly serve
customer satisfaction – the highest priority according to the
phrasing of the first agile principle in the Agile Manifesto. Most
likely the customer won’t request documentation that is intended
to support a programming-related matter. Usually such matters are
not understood by non-developers at all. Thus the developers have
to initiate a documentation for the purpose of supporting Program
Comprehension.
Certainly, this is not problematic as long as the customer
appreciates quality to a certain extent. In that case the ninth
agile principle approves autonomous documenting (“Continuous
attention to technical excellence and good design enhances
agility.“). But if the customer does not appreciate quality to
such an extent, the developers have a problem. After all, you
cannot disregard customer satisfaction as “our highest priority”.
To prevent such a situation, we should have a secondary, more
discernible benefit apart from the primary one (support of Program
Comprehension) to justify the effort of documenting. As quoted
here from a research paper, there actually seems to be an
appropriate further value of Design Decision Rationales in general:
“Managers or users can use them to evaluate the design. Lawyers
can use them to determine if the design is intellectual property.”
1
Nonetheless, we don’t have to think that far beyond ordinary
software development (lawyers are usually not involved as project
stakeholder, aren’t they?). Instead, think of a facilitation of a
crude change impact analysis conducted by a project manager as
a non-developer stakeholder. This facilitation could feasibly occur
through Design Decision Rationales which are understandable – at
least partially – for non-developers.
A documentation based on Design Decision Rationales as shown in
this article might not be hard to introduce. Most likely you already
use a code documentation tool which you can extend for that aim.
So why not trying to document your decisions instead of (only) the
results of those? Certainly, you can argue that practicing this idea
is not necessarily lightweight enough. But by experimenting with
it, you can at least gain some practical documentation inspiration
specific to agile software development!