The document discusses the Agile manifesto's stance on documentation in software development, emphasizing the need for valuing individuals and interactions over comprehensive documentation. It explores various definitions of documentation and highlights the distinction between source code documentation and system documentation from different perspectives. Additionally, it suggests that effective Agile documentation should focus on communication, maintain stability, and be created at the right time during the development lifecycle.

1. Fabian Kiss
Sep 2011
Scrum User Group Lake Constance

2. DO AGILISTES NEED DOCUMENTATION?

3. THE MANIFESTO ON DOCUMENTATION
Manifesto for Agile Software Development
We are uncovering better ways of developing
software by doing it and helping others do it.
Through this work we have come to value:
Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
That is, while there is value in the items on
the right, we value the items on the left more.

4. THE MANIFESTO ON DOCUMENTATION
Manifesto for Agile Software Development
We are uncovering better ways of developing
software by doing it and helping others do it.
Through this work we have come to value:
Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
That is, while there is value in the items on
the right, we value the items on the left more.

5. LET'S HAVE A CLOSER
LOOK AT SOME DEFINITIONS

6. AGILE PROCESS
 Definition by values and practices (Manifesto & beyond)

7. AGILE PROCESS
Agile Software Development Poster by VersionOne, Inc., 2011, licensed under the CC BY-SA 3.0

8. AGILE PROCESS
 Definition by values and practices (Manifesto & beyond)
 Definition by “SDLC coverage”

9. AGILE PROCESS
From Agile Software Development Methods: Review and Analysis by Abrahamsson, P., Salo, O., Ronkainen, J., & Warsta, J., 2002, licensed under the CC BY-SA 3.0

10. AGILE PROCESS
 Definition by values and practices (Manifesto & beyond)
 Definition by “SDLC coverage”
 Definition by ...
There is a common understanding of what an agile software
development process is

11. DOCUMENTATION
Virtually no definition of documentation
(in respect of software development)

12. DOCUMENTATION
Virtually no definition of documentation
(in respect of software development)
 From the developer's perspective: source code documentation
 From the project stakeholder's perspective: system documentation

13. DOCUMENTATION
Virtually no definition of documentation
(in respect of software development)
 From the developer's perspective: source code documentation
 From the project stakeholder's perspective: system documentation
 More general: software documentation
 Umbrella term for any documentation related to a software product

14. DOCUMENTATION
Virtually no definition of documentation
(in respect of software development)
 From the developer's perspective: source code documentation
 From the project stakeholder's perspective: system documentation
 More general: software documentation
 Umbrella term for any documentation related to a software product
People think of different things when referring to documentation

16. DOCUMENTATION
Proposal for an initial classification:
Documentation dealing with properties of a software product ...
 ... during its development
 ... after its completion

17. BOOKS ABOUT AGILE DOCUMENTATION
Picture by Jeremy Nelson, licensed under the CC BY-NC-SA 2.0

18. S.W. AMBLER: 'AGILE MODELING'
Scott W. Ambler
Agile Modeling: Effective Practices for
eXtreme Programming and the Unified Process
Wiley
2002

19. S.W. AMBLER: 'AGILE MODELING'
Chapter about agile documentation
(www.agilemodeling.com holds a more recent version of it)
Values, principles and practices for Agile Modeling adopted from
XP/Agile values, principles and practices

20. S.W. AMBLER: 'AGILE MODELING'
One of his values in the context of documentation:
“The fundamental issue is communication, not documentation.”
From Agile/Lean Documentation: Strategies for Agile Software Development by Scott W. Ambler, http://www.agilemodeling.com/essays/agileDocumentation.htm#CriticalPoints

21. S.W. AMBLER: 'AGILE MODELING'
One of his principles in the context of documentation:
“Travel Light. Every artifact that you create, and then decide to keep, will
need to be maintained over time.”
From Agile Modeling (AM) Principles v2 by Scott W. Ambler, http://www.agilemodeling.com/principles.htm#TravelLight

22. S.W. AMBLER: 'AGILE MODELING'
Two of his practices in the context of documentation:
“Executable specifications, for example [...] a developer test-suite [...].
Because these artifacts add value there is a significantly greater chance
that developers will keep them up-to-date.”
From Agile/Lean Documentation: Strategies for Agile Software Development by Scott W. Ambler,
http://www.agilemodeling.com/essays/agileDocumentation.htm#IssuesWithDocumentation

23. S.W. AMBLER: 'AGILE MODELING'
Two of his practices in the context of documentation:
“Executable specifications, for example [...] a developer test-suite [...].
Because these artifacts add value there is a significantly greater chance
that developers will keep them up-to-date.”
From Agile/Lean Documentation: Strategies for Agile Software Development by Scott W. Ambler,
http://www.agilemodeling.com/essays/agileDocumentation.htm#IssuesWithDocumentation
"Document stable concepts, not speculative concepts, and thereby document
as late as possible in the life cycle."
From Agile/Lean Documentation: Strategies for Agile Software Development by Scott W. Ambler,
http://www.agilemodeling.com/essays/agileDocumentation.htm#WhenToCreateDocumentation

24. S.W. AMBLER: 'AGILE MODELING'
Two of his practices in the context of documentation:
“Executable specifications, for example [...] a developer test-suite [...].
Because these artifacts add value there is a significantly greater chance
that developers will keep them up-to-date.”
From Agile/Lean Documentation: Strategies for Agile Software Development by Scott W. Ambler,
http://www.agilemodeling.com/essays/agileDocumentation.htm#IssuesWithDocumentation
"Document stable concepts, not speculative concepts, and thereby document
as late as possible in the life cycle." t
From Agile/Lean Documentation: Strategies for Agile Software Development by Scott W. Ambler,
whe n to documen
http://www.agilemodeling.com/essays/agileDocumentation.htm#WhenToCreateDocumentation

25. THE DOWNSIDE...

26. S.W. AMBLER: 'AGILE MODELING'
Strongly influenced by Agile Modeling (the author's major interest)
 AM as a certain agile methodology
 AMDD as a certain software development approach

27. S.W. AMBLER: 'AGILE MODELING'
Strongly influenced by Agile Modeling (the author's major interest)
 AM as a certain agile methodology
 AMDD as a certain software development approach
Limits generality

28. A. RÜPING: 'AGILE DOCUMENTATION'
Andreas Rüping
Agile Documentation: A Pattern Guide to Producing
Lightweight Documents for Software Projects
Wiley
2003
(It's
a
app comple
a
can rently tely dif
not t f
fr o n affo he pub erent b
rd d l
t co
v er esig isher s ook,
fo r ning imp
each a un l y
of i t ique
s bo
oks)

29. A. RÜPING: 'AGILE DOCUMENTATION'
Patterns as descriptions of solutions to certain documentation issues in
agile software projects, divided into five categories:
1. Finding the Right Topics
2. Structuring Individual Documents
3. Layout and Typography
4. Infrastructure and Technical Organisation
5. Management and Quality Assurance

30. A. RÜPING: 'AGILE DOCUMENTATION'
Examples (“Pattern Thumbnails”):
From Agile Documentation: A Pattern Guide to Producing Lightweight Documents for Software Projects by Andreas Rüping, 2003, Wiley, p. 198

31. A. RÜPING: 'AGILE DOCUMENTATION'
Examples (“Pattern Thumbnails”):
From Agile Documentation: A Pattern Guide to Producing Lightweight Documents for Software Projects by Andreas Rüping, 2003, Wiley, p. 198
From Agile Documentation: A Pattern Guide to Producing Lightweight Documents for Software Projects by Andreas Rüping, 2003, Wiley, p. 201

32. A. RÜPING: 'AGILE DOCUMENTATION'
Furthermore...
“Different people grasp information at different speeds. […] Documents
[…] allow people to read at their own pace.”
From Agile Documentation: A Pattern Guide to Producing Lightweight Documents for Software Projects by Andreas Rüping, 2003, Wiley, p. 20

33. A. RÜPING: 'AGILE DOCUMENTATION'
Furthermore...
“Different people grasp information at different speeds. […] Documents
[…] allow people to read at their own pace.”
From Agile Documentation: A Pattern Guide to Producing Lightweight Documents for Software Projects by Andreas Rüping, 2003, Wiley, p. 20
agile principle
s' relation to ind
ividuals

34. AGAIN, A
DOWN-
SIDE...

35. A. RÜPING: 'AGILE DOCUMENTATION'
Obviously the patterns are more or less specific to agile software
development

36. A. RÜPING: 'AGILE DOCUMENTATION'
Obviously the patterns are more or less specific to agile software
development
Some problems unique for documentation in agile software
development might not be addressed at all

37. Picture by César Astudillo, licensed under the CC BY-NC 2.0

38. Documentation itself is simply a too broad topic ...

39. Documentation itself is simply a too broad topic ...
… even agile documentation is still something
very unspecific

40. SOME OPTIMISM PLEASE!
Picture by LawPrieR, licensed under the CC BY-NC 2.0

41. Before considering (or developing) any practices, patterns or other forms
of advice for agile documentation, we should further delimit the scope!

42. Before considering (or developing) any practices, patterns or other forms
of advice for agile documentation, we should further delimit the scope!

43. Before considering (or developing) any practices, patterns or other forms
of advice for agile documentation, we should further delimit the scope!
 Documentation for during/after development

44. Before considering (or developing) any practices, patterns or other forms
of advice for agile documentation, we should further delimit the scope!
✔ Documentation for during/after development
 Who documents for whom?

45. Before considering (or developing) any practices, patterns or other forms
of advice for agile documentation, we should further delimit the scope!
✔ Documentation for during/after development
 Who documents for whom?
 Documenting for what specific purpose?

46. Before considering (or developing) any practices, patterns or other forms
of advice for agile documentation, we should further delimit the scope!
✔ Documentation for during/after development
 Who documents for whom?
 Documenting for what specific purpose?
 ...