5. Common belief: Comments are bad and get outdated,
just strive for writing self-documenting code
Yes, we should aim for that, but the code does not tell
the whole story
Why documentation?
6. If you are new to an ongoing software project, where do
you start?
Still you need to know a lot of things:
• What is the overall architecture?
• Are there naming conventions?
• What design principles are in place?
• How is the layering?
• What frameworks?
• etc…
Why documentation?
7. The code does not portray the intent of the design
Perhaps it is easy to understand what the software does
on a high-level, but we still need to understand:
• How does the system fit in the existing landscape
• Why the technologies were chosen
• Overall structure
• Interconnections between subsystems
• Logging strategy
• Design patterns
• etc…
Why documentation?
10. “Working software over comprehensive documentation”
- The Agile Manifesto
For many this means: no documentation
How can complex enterprise software need
no documentation, when a $20 toaster has
one
Practical experience says that there are
things that need explanation, a guidebook
Documentation Guidebook
11. Problem is that developers on a software team think
documentation is writing Microsoft Word documents and
UML software - all of which get outdates fast
And who will read such outdated material?
Documentation Guidebook
12. Navigating from Detail to Big Picture
Maps help you navigate
foreign countries
If you get dropped in a
place you need to “zoom
out” to see the whole
picture
Visualising software with
the C4 approach
13. Navigating from Detail to Big Picture
Sights help you understand the nature of the country
The codebase is to large to go though but if you know where the
interesting parts are, it will help
For example, you might look at one Input Controller and how it
connects to the model and the view - you don’t need to look at
the other hundred or so since you know get it
14. Navigating from Detail to Big Picture
History and culture help you understand the people and their
ways of doing things and why
It helps if you know the motivation and reasons why the
software is like it is
You get a lot of understanding if you know the motivations
and preferences of the people that are working on the
software
15. Navigating from Detail to Big Picture
Practical information such as currency, power outlets, laws,
customs etc help you
You need to how where the codebase is, what tools to install, the
URL to stuff and so on
It’s all the stuff that can help the development team to do their
job effectively
16. Keep it short, keep it simple
Since the code doesn’t tell the whole story, some
supplementary documentation is needed
This documentation can be thought of as a guidebook
Should contain enough information but not too much detail as
these are the things that change and the story the code tells
anyways
Consise, to the point text is need
17. Beware of the “views”
Some documentation emphasis showing diffrent view like the
“logical view” and “physical view” etc.
These are fine, but tend to very confusing and make people
hate documentation (as if that was hard)
Better approach is to write clear, no bullshit, like it is
documentation
18. Product vs. Project Documentation
Projects are temporary undertakings that are timeboxed,
products last many projects
Project documentation should specify what is needed to
make the project succeed and gets outdates when the project
is over
Product documentation should specify how the product
works at any time
19. Software Guidebook
These sections might be in such a guidebook:
Context
Functional Overiew
Quality Attributes
Constraints
Principles
Software Architecture
External Interfaces
Code
Data
Infrastructure Architecture
Deployment
Operation and Support
Decision Log
20. Context
A context section is one of the first sections and should set
the scene for the rest of the document
Intent Should answer the following questions:
•What is the software product all about?
•What is it that’s being built?
•How does it fit into the existing environment?
•Who is using it?
Structure Does not need to be long, 1-2 pages with
context diagram
21. Context
A context section is one of the first sections and should set
the scene for the rest of the document
Motivation Give the readers the overview so they know what
is to follow
Audience Technical and non-technical, inside or outside
the team
22. Functional Overview
Expand on the context and summarise the major function of
the software
Intent Summarise the key functions, should make clear:
• What the system actually does
• Features, functions, user stories etc are
• Who the users are
• How this shapes and defines the architecture
Structure This acts as a summary of functionality and
shows the most defining functions without
replacing the actual detailed users stories
23. Motivation Should not be long but should show what the
system actually does where the context shows
where it fits in
Audience Technical and non-technical, inside or outside
the team
Functional Overview
Expand on the context and summarise the major function of
the software
24. Quality Attributes
Specifies the non-functional attributes of the system
Intent Should specify the quality attributes
• Performance, uptime etc
• Realistic and measurable not some fancy words
• Things that are granted should be stated
• Any unrealistic attributes should be address
Structure Listing such as performance, scalability,
availability, security, extensibility, flexibility,
monitoring, disaster recovery etc…
“System should be fast” is unacceptable
25. Motivation Putting this in writing removes any ambiguity
Audience Technical people mostly
Quality Attributes
Specifies the non-functional attributes of the system
Required Yes
26. Contraints
Software system always have contraints. This section should
document those.
Intent Should explicitly summarise the constraints that the
team is working within, and all the decisions that
have been made for you
Structure Listing such time, budget and resource,
approved technology, deployment platform,
existing system, localisation, protocols allowed,
legal requirements etc.
27. Motivation Contraints massively influence architecture
Audience Everybody involved in the development process
as some constraints are not technical
Required Yes
Contraints
Software system always have contraints. This section should
document those.
28. Principles
Summary of the principles used to design and build the
software
Intent Principles that are important need to be specified
to be adopt and followed
Structure Listing such Layering, no logic in the view, no
logic in the database, use ORM, use
Dependancy Injection, follow SOLID, DRY etc.
29. Motivation Since principles help consistency and ensure
that common problems are solved in the same
way, it is important tok make them explicit so
everyone on the team understands what they are
Audience Development Team
Required Yes
Principles
Summary of the principles used to design and build the
software
30. Software Architecture
This is the “big picture” and allows you to show the structure
of the software
Intent Summary of the software architecture should
answer these questions:
• What is the big picture
• What is the structure, major containers,
components and interactions
• etc…
Structure Container and component diagrams with short
narrative of what the diagrams are showing
31. Motivation This is the map that will guide you
Audience Development Team
Required Yes
Software Architecture
This is the “big picture” and allows you to show the structure
of the software
32. External Interfaces
Interfaces with external systems is the riskiest part of the
software and needs to be summarised
Intent Summary of key interfaces, technical and non-
technical perspective
Structure List of external interfaces, with component
diagrams, and information on where to find
documentation, and who is responsible on both
ends
33. Motivation This need to be covered since it is easily
underestimated but contains a lot of risk
Audience Development Team
Required Only if there are risky interfaces
External Interfaces
Interfaces with external systems is the riskiest part of the
software and needs to be summarised
34. Code
This sections presents a lower level explanation on how
things work
Intent Describe in detail how important and complex
things in the software work, for example MVC,
application life-cycle management, state handing
etc.
Structure Short, concise sections, aided with diagrams,
that explain each topic
35. Motivation Ensure that everybody on the team understands
complex things about the software
Audience Development Team
Required No, but most software needs this
Code
This sections presents a lower level explanation on how
things work
36. Data
Record data is important in enterprise systems and the data
strategy needs to be clarified
Intent Explain the data model, how it is stored and where,
what are backup storage and redundancy
strategies etc.
Structure Short, concise sections, aided with diagrams,
that explain the data strategy
37. Motivation Data tends to outlive the software, so it is
necessary to explain the strategy
Audience Development Team
Required No, but most software with data needs this
Data
Record data is important in enterprise systems and the data
strategy needs to be clarified
38. Infrastructure Architecture
Infrastructure is a big part of software since software needs
to be stored and operated in a physical hardware
environment
Intent Outline the physical setup, hardware, use of
virtualisation, redundancy, failover, load balancers
etc.
Structure Network diagrams with explanations
39. Motivation Software must be run somewhere in a physical
setup and this explains how the setup is
Audience Technical people, network operators
Required Yes
Infrastructure Architecture
Infrastructure is a big part of software since software needs
to be stored and operated in a physical hardware
environment
40. Deployment
Deployment explains how software is installed on the
hardware
Intent Describe the mapping of software and the
hardware, how and where software is installed and
configured
Structure Tables showing mapping and deployment
diagrams with explanation
41. Motivation Gives understanding on how the software will
actually work when running
Today you want to automate this things as much
as possible with tools such as Puppet and Chef
Audience Technical people, network operators
Required Yes
Deployment
Deployment explains how software is installed on the
hardware
42. Operation and Support
Describes how people will monitor, run and manage the
software
Intent How monitoring and managing the system is done,
where the log files are, configurations, manual
housekeeping stuff etc
Structure Narrative explaining each topic
43. Motivation How to operate the software must be
documented, all file locations and so on
Audience Technical people, network operators
Required Yes
Operation and Support
Describes how people will monitor, run and manage the
software
44. Decision Log
Log of decision made during the development phase
Intent Document for reference any major decision and the
reason for them, why some technology was chosen
and so on
Structure Simple list of decisions
45. Motivation Software development is complex and major
decision are made for reasons, but can be
forgotten
People tend to avoid responsibility so keeping
track of decision and their reasons can save a lot
of discussion later
Audience Technical people, operation
Required No, but really useful
Decision Log
Log of decision made during the development phase
46. Summary
Yes, we need documentation, the code does not say it all and
agile does not gives us excuses
Software Guidebook is a really useful tool
