HÖNNUN OG SMÍÐI HUGBÚNAÐAR 2015L16 Documenting Software
Agenda
Why documentationSoftware Guidebook
Reading
Brown textbook 48-63
Why documentation?
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?
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?
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?
Why documentation?
Documentation Guidebook
“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
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
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
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
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
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
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
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
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
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
ContextA 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
ContextA 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
Functional OverviewExpand 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
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 OverviewExpand on the context and summarise the major function of the software
Quality AttributesSpecifies 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
Motivation Putting this in writing removes any ambiguity
Audience Technical people mostly
Quality AttributesSpecifies the non-functional attributes of the system
Required Yes
ContraintsSoftware 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.
Motivation Contraints massively influence architecture
Audience Everybody involved in the development process as some constraints are not technical
Required Yes
ContraintsSoftware system always have contraints. This section should document those.
PrinciplesSummary 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.
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
PrinciplesSummary of the principles used to design and build the software
Software ArchitectureThis 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
Motivation This is the map that will guide you
Audience Development Team
Required Yes
Software ArchitectureThis is the “big picture” and allows you to show the structure of the software
External InterfacesInterfaces 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
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 InterfacesInterfaces with external systems is the riskiest part of the software and needs to be summarised
CodeThis 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
Motivation Ensure that everybody on the team understands complex things about the software
Audience Development Team
Required No, but most software needs this
CodeThis sections presents a lower level explanation on how things work
DataRecord 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
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
DataRecord data is important in enterprise systems and the data strategy needs to be clarified
Infrastructure ArchitectureInfrastructure 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
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 ArchitectureInfrastructure is a big part of software since software needs to be stored and operated in a physical hardware environment
DeploymentDeployment 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
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
DeploymentDeployment explains how software is installed on the hardware
Operation and SupportDescribes 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
Motivation How to operate the software must be documented, all file locations and so on
Audience Technical people, network operators
Required Yes
Operation and SupportDescribes how people will monitor, run and manage the software
Decision LogLog 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
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 LogLog of decision made during the development phase
SummaryYes, we need documentation, the code does not say it all and agile does not gives us excuses
Software Guidebook is a really useful tool
Agenda
Why documentationSoftware Guidebook