Documentation for Program Comprehension in Agile Software Development

867
-1

Published on

Most of the daily work of a software developer is maintenance and further development of existing software products. Is there a kind of documentation which particularly facilitates these tasks? Can such a documentation be agile?

Published in: Technology
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
867
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
8
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

Documentation for Program Comprehension in Agile Software Development

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

×