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