Software teams often struggle with deciding what documentation is necessary for their own development lifecycle. Many software systems end up varying between no documentation at all or tons of paper which are useless and/or outdated.
This page defines a minimum set of documents that should provide the necessary information for its stakeholders and to enable them on understanding and taking correct decisions about the system.
The list was inspired by a tweet from @simonbrown. In order to record it for my own benefit and to serve as research material for the software community I decided to create this page.
When talking about documentation it is important to keep in mind that each document is created with one or more target stakeholders. In the software context, I will abstractly define three types of stakeholders:
- Developers: who implement, maintain and evolve the system
- Users: who operate the system
- Other systems' developers: who integrate with the system via a provided interface
This page limits its scope to stakeholders of type 1 and 3. Users require documents of a different nature, such as "User Manuals" and "Procedures", which are not included in this list.
"A System Context diagram is a good starting point for diagramming and documenting a software system, allowing you to step back and see the big picture. Draw a diagram showing your system as a box in the centre, surrounded by its users and the other systems that it interacts with.
Detail isn't important here as this is your zoomed out view showing a big picture of the system landscape. The focus should be on people (actors, roles, personas, etc) and software systems rather than technologies, protocols and other low-level details. It's the sort of diagram that you could show to non-technical people." (1)
"Once you understand how your system fits in to the overall IT environment, a really useful next step is to zoom-in to the system boundary with a Container diagram. A "container" is something like a server-side web application, single-page application, desktop application, mobile app, database schema, file system, etc. Essentially, a container is a separately runnable/deployable unit (e.g. a separate process space) that executes code or stores data.
The Container diagram shows the high-level shape of the software architecture and how responsibilities are distributed across it. It also shows the major technology choices and how the containers communicate with one another. It's a simple, high-level technology focussed diagram that is useful for software developers and support/operations staff alike." (1)
"A deployment diagram allows you to illustrate how containers in the static model are mapped to infrastructure. This deployment diagram is based upon a UML deployment diagram, although simplified slightly to show the mapping between containers and deployment nodes. A deployment node is something like physical infrastructure (e.g. a physical server or device), virtualised infrastructure (e.g. IaaS, PaaS, a virtual machine), containerised infrastructure (e.g. a Docker container), an execution environment (e.g. a database server, Java EE web/application server, Microsoft IIS), etc. Deployment nodes can be nested.
You may also want to include infrastructure nodes such as DNS services, load balancers, firewalls, etc." (1)
A collection of records for "architecturally significant" decisions like those that affect the system structure, non-functional characteristics, dependencies, interfaces, or construction techniques. (2)
As evolutionary architecture has been recommended as an alternative to traditional up-front, heavy-weight enterprise architectural designs, decisions have become more frequent in the lifecycle of a software system. Keeping record of such decisions is proven to be very helpful when the need of new changes emerge. To be able to clearly revisit the reasons (why) certain decisions have been made and what were the forces and alternatives considered previously may be a valuable input data to make a consistent and efficient new decision.
The following template provides a fluent way to write down ADRs:
ADR 1: [decision title]
In [a system, context] facing [a requirement, situation, challenge]
we decided [decision] and not [alternatives]
to achieve [goal, benefits] accepting [constraints, drawbacks]
Beyond the previous document, extra information may still be needed to guide the stakeholders in the software. Lightweight Markdown files can fulfill this need with documents close to the source code (and possibly versioned), searcheable, easily updatable and nicely formatted.
There are references and templates that might inspire the fullfilment of this section (on-demand basis), such as the Software Guidebook or arc42.
When providing an interface to other developers (Class Library, Web API, etc) it is fundamental that clients can easily understand and get acquainted with consuming the provided functionalities.
Lightweight markdown files with a "Getting Started" or "How To" sections will come as a piece of cake and will increase the satisfaction of your fellow colleagues.
It is essential that developers have useful and immediate feedback when coding against an API. This is usually achieved with an IDE with code-completion capabilities. In Visual Studio that is called IntelliSense.
When providing .NET Class Libraries, do provide useful information of all your public types by exporting the XML comments to your consumers.
(1) Quoted text and images by Simon Brown, licensed under Creative Commons. The System Context diagram and the Container diagram are part of the C4 Model Core diagrams. Access the C4 Model website for details.
(2) More information on Documenting Architecture Decisions: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions