![Page 1: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/1.jpg)
Documentation for Program Comprehension in
Agile Software Development
Fabian Kiss
Scrum User Group Lake Constance
Sep 2011
![Page 2: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/2.jpg)
Program Comprehension
To understand a completed computer program (source code)What has been implemented? How?
![Page 3: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/3.jpg)
Agile
Working software over comprehensive documentation
→ code = documention
![Page 4: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/4.jpg)
Why supporting Program Comprehension by
documentation?
Agile supports Program Comprehension
◮ Striving for high-quality source code (Clean Code,Refactoring)
◮ Exemplification of the program’s ”use” through Unit Tests
![Page 5: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/5.jpg)
Why supporting Program Comprehension by
documentation?
Agile supports Program Comprehension
◮ Striving for high-quality source code (Clean Code,Refactoring)
◮ Exemplification of the program’s ”use” through Unit Tests
![Page 6: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/6.jpg)
Why supporting Program Comprehension by
documentation?
Agile supports Program Comprehension
◮ Striving for high-quality source code (Clean Code,Refactoring)
◮ Exemplification of the program’s ”use” through Unit Tests
![Page 7: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/7.jpg)
Why supporting Program Comprehension by
documentation?
Agile impedes Program Comprehension
◮ Continuous refactoring
◮ Experienced team for initial development, less experiencedteam for maintenance
◮ Unrefactorable obfuscating code
◮ Face-to-face communication is preferred: What if nobody(anymore) knows a certain information?
![Page 8: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/8.jpg)
Why supporting Program Comprehension by
documentation?
Agile impedes Program Comprehension
◮ Continuous refactoring
◮ Experienced team for initial development, less experiencedteam for maintenance
◮ Unrefactorable obfuscating code
◮ Face-to-face communication is preferred: What if nobody(anymore) knows a certain information?
![Page 9: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/9.jpg)
Why supporting Program Comprehension by
documentation?
Agile impedes Program Comprehension
◮ Continuous refactoring
◮ Experienced team for initial development, less experiencedteam for maintenance
◮ Unrefactorable obfuscating code
◮ Face-to-face communication is preferred: What if nobody(anymore) knows a certain information?
![Page 10: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/10.jpg)
Why supporting Program Comprehension by
documentation?
Agile impedes Program Comprehension
◮ Continuous refactoring
◮ Experienced team for initial development, less experiencedteam for maintenance
◮ Unrefactorable obfuscating code
◮ Face-to-face communication is preferred: What if nobody(anymore) knows a certain information?
![Page 11: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/11.jpg)
Why supporting Program Comprehension by
documentation?
Agile impedes Program Comprehension
◮ Continuous refactoring
◮ Experienced team for initial development, less experiencedteam for maintenance
◮ Unrefactorable obfuscating code
◮ Face-to-face communication is preferred: What if nobody(anymore) knows a certain information?
![Page 12: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/12.jpg)
Goal
Documenting particularly for the support of ProgramComprehension without impeding agility
→ requirements for that documentation...
![Page 13: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/13.jpg)
Low-level context
Documentation has to be attached to the software indevelopment at a low-level context (source code)
Rationale
◮ Program Comprehension is a matter of programming
◮ Meeting ”the code is the documentation”
◮ Agile itself ”lives” at a low-level context (agile practices)
![Page 14: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/14.jpg)
Low-level context
Documentation has to be attached to the software indevelopment at a low-level context (source code)
Rationale
◮ Program Comprehension is a matter of programming
◮ Meeting ”the code is the documentation”
◮ Agile itself ”lives” at a low-level context (agile practices)
![Page 15: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/15.jpg)
Low-level context
Documentation has to be attached to the software indevelopment at a low-level context (source code)
Rationale
◮ Program Comprehension is a matter of programming
◮ Meeting ”the code is the documentation”
◮ Agile itself ”lives” at a low-level context (agile practices)
![Page 16: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/16.jpg)
Low-level context
Documentation has to be attached to the software indevelopment at a low-level context (source code)
Rationale
◮ Program Comprehension is a matter of programming
◮ Meeting ”the code is the documentation”
◮ Agile itself ”lives” at a low-level context (agile practices)
![Page 17: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/17.jpg)
High-level benefit
From the low-level documentation a higher-leveldocumentation (artifact) has to be extracted such that itadds directly a benefit for other involved stakeholders:
1. Progress of software development is made moretransparent
2. Improved quality of developed software product /additional value
![Page 18: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/18.jpg)
High-level benefit
From the low-level documentation a higher-leveldocumentation (artifact) has to be extracted such that itadds directly a benefit for other involved stakeholders:
1. Progress of software development is made moretransparent
2. Improved quality of developed software product /additional value
![Page 19: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/19.jpg)
High-level benefit
From the low-level documentation a higher-leveldocumentation (artifact) has to be extracted such that itadds directly a benefit for other involved stakeholders:
1. Progress of software development is made moretransparent
2. Improved quality of developed software product /additional value
![Page 20: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/20.jpg)
High-level benefit
Rationale
◮ 1st type: agile principle ”working software is the primarymeasure of progress”
◮ 2nd type: agile principle ”continuous attention to technicalexcellence and good design enhances agility”
◮ Such a direct benefit – obtained by the low-leveldocumentation – helps a developer to justify the effort for(continually) documenting at a low level
![Page 21: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/21.jpg)
High-level benefit
Rationale
◮ 1st type: agile principle ”working software is the primarymeasure of progress”
◮ 2nd type: agile principle ”continuous attention to technicalexcellence and good design enhances agility”
◮ Such a direct benefit – obtained by the low-leveldocumentation – helps a developer to justify the effort for(continually) documenting at a low level
![Page 22: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/22.jpg)
High-level benefit
Rationale
◮ 1st type: agile principle ”working software is the primarymeasure of progress”
◮ 2nd type: agile principle ”continuous attention to technicalexcellence and good design enhances agility”
◮ Such a direct benefit – obtained by the low-leveldocumentation – helps a developer to justify the effort for(continually) documenting at a low level
![Page 23: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/23.jpg)
No separate artifact
A documentation for supporting Program Comprehensionmust not be explicitly produced, as it is not explicitlyrequested (by the customer)
Rationale
◮ Agile principle: ”simplicity – the art of maximizing theamount of work not done – is essential”
◮ Overdoing low-level documentation in favor of thesubsequently extracted high-level documentation artifact isnot necessary
![Page 24: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/24.jpg)
No separate artifact
A documentation for supporting Program Comprehensionmust not be explicitly produced, as it is not explicitlyrequested (by the customer)
Rationale
◮ Agile principle: ”simplicity – the art of maximizing theamount of work not done – is essential”
◮ Overdoing low-level documentation in favor of thesubsequently extracted high-level documentation artifact isnot necessary
![Page 25: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/25.jpg)
No separate artifact
A documentation for supporting Program Comprehensionmust not be explicitly produced, as it is not explicitlyrequested (by the customer)
Rationale
◮ Agile principle: ”simplicity – the art of maximizing theamount of work not done – is essential”
◮ Overdoing low-level documentation in favor of thesubsequently extracted high-level documentation artifact isnot necessary
![Page 26: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/26.jpg)
Primary purpose
A documentation for supporting Program Comprehensionhas to serve primarily that purpose
Rationale
◮ A specific purpose is needed as a starting point, because”documentation” is too broad
◮ Alternatively presuming particular documentation artifactsfrom software development process violates generality
![Page 27: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/27.jpg)
Primary purpose
A documentation for supporting Program Comprehensionhas to serve primarily that purpose
Rationale
◮ A specific purpose is needed as a starting point, because”documentation” is too broad
◮ Alternatively presuming particular documentation artifactsfrom software development process violates generality
![Page 28: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/28.jpg)
Primary purpose
A documentation for supporting Program Comprehensionhas to serve primarily that purpose
Rationale
◮ A specific purpose is needed as a starting point, because”documentation” is too broad
◮ Alternatively presuming particular documentation artifactsfrom software development process violates generality
![Page 29: Documentation for Program Comprehension in Agile Software Development](https://reader034.vdocument.in/reader034/viewer/2022051608/5456c78db1af9fba5d8b46df/html5/thumbnails/29.jpg)
How a concrete solution could look like?
An exemplary documentation technique meeting all therequirements:
Code documentation based on Design Decision Rationales
http://www.infoq.com/articles/decision-rationales-program-comprehension