SW Documentation
Software architecture documentation takes place on the wiki, using PlantUML to include diagrams. The documentation is structured as a hierarchy of "building blocks", starting from the whole architecture landscape comprising "everything at a glance" and down to all the components, frameworks, services etc. with all their details that contribute to the realizing the actual system.
Each building block, unless its considered too small, has its own wiki <space> that is placed within the overall building block catalog. Too small building blocks are simply part of the bigger building blocks they are part of.
This page describes to structure and fill in such a wiki <space>. Creating the Wiki <Space>
The wiki <space> must be given the name of the building block; for example "AccountIT".
<Home> (should be the name of building block, not just the generic "Home").
Brief introductory text focusing on the important goals, challenges and other such aspects Diagram illustrating the building block "at a glance", including important aspect such as interface and external dependencies; the diagram could be taken from the solution concept (as a reference, not a copy) Architecture navigator, when relevant
A. Scope and Vision
The purpose of this section is to "set the scene" for building block; ideally it should be created before the other sections The purpose of this section is to provide an introduction and overview The audience of this section should ideally be anybody A1. Solution Concept The purpose of this section is to provide a quick overview of the architecture, and is considered the most important part of the documentation The purpose of this section is to briefly explain the motivation for the architecture "Rich diagram" introducing the building block at a glance; should include both the CURRENT, actually implemented state, as well as the FUTURE "vision" of what the building block is intended to become sometime in the future A brief text justifying the building block and its architecture/design; why the building block is created in the first place, and why it is created the way it is; for example "by introducing X, we can separate the A from the B, which leads to the following benefits ..." Risks and mitigation; risks related to architecture - the underlying technology, the interaction with other building blocks etc., and how these risk can be mitigated A2. Goals and Requirements The purpose of this section is to explain the value and the goals for the building block, and how they are fulfilled Purpose and Goals in the form of a table, including a short description of how they are fulfilled Use Cases Use cases should only be included when they are not already provided from SOMA as part of the business requirements/design; in that case a simple reference will do Use case diagram with associated use case flows in bullet form; even for lower level building blocks its still relevant to describe the value they provide to whom ("whom" can also refer to other building blocks and not people) Record of which parts of the use cases (slices) that have been implemented in which version Non-Functional Requirements in the form of a table, and taken from the common taxonomy; should include a short description of how they are fulfilled Business strategy, vision, context and motivation, when relevant A3. Terminology The purpose of this section is to define the common terminology used List of terms, or references to such lists if they already exist on other pages; or a mix of both A4. Versions The purpose of this section is to communicate the state of the building block; how much of it is implemented/released? Etc. The purpose of this section is to have a record of improvements, extensions etc. that could/should be created later What is implemented, what is not Version history / "release notes" Missing parts, open items, issues
B. Research
The purpose of this section is to have a "playground" for analyzing problems and evolving solutions before they are integrated formally into the other sections of the wiki space, mainly "development" below POC material, discussions and general analysis addressing central challenges and difficulties, or drafts of solutions Background material and references Evaluations and decision log
C. Development
The purpose of this section is to document how the building block is implemented; its interfaces, inner workings and other such details The audience of this section would normally be R&D C1. Interfaces The purpose of this section is to describe how the building block fits into a wider context, and how it interacts with other building blocks as well as external systems The purpose of this section is to provide a formal specification for the interface, targeted at the "consumers" of the building block List of logical/business "operations" (functions, methods) that the building block can do through its interface "Context diagram", or communication diagram, i.e. semi-formal diagram illustrating how the building block fits into and communicates with a wider context Formal interface specification and documentation, depending on the type of building block, may include UML sequence diagrams or BPMN's Interface versions UML communication diagrams UX wireframes, when relevant C2. Data The purpose of this section is to describe all aspects related to the building block's data; schema, states, migration, even important in-memory data structures etc. Logical and physical data models UML state diagrams Schema versions Migration and roll-off strategies Lists of enums etc. C3. Internal Structure and Behavior The purpose of this section is to describe how the building block is constructed; its inner structure and workings List/diagram of sub-components Activity flows, algorithms, sequence diagrams, threading model and other internal behavior Class diagrams etc. Software structure, namespaces etc. C4. Technology The purpose of this section is to describe the underlying technology that the building block is supposed to run on Technology stack Description of (third party) technologies used, including frameworks, DBMS, etc. Node architecture Underlying hardware, requirements to the hardware, etc.
D. Test
Test strategy (for the building block, is it manual or automatic etc.) Unit tests Automatic system tests Runtime/production tests (self-test)
E. Deployment
The purpose of this section is to document the design and data for the installation and deployment of the building block The purpose of this section is NOT to provide an operation manual per se, but may provide the necessary input to such a manual The audience of this section would normally be R&D and Operations Installation and configuration
M. Informative
The purpose of this section is to collect various informal information related to the building block, that is not "normative", i.e. part of the specification and technical documentation in the sections above The audience of this section should ideally be anybody M1. Presentations The purpose of this section is to collect presentations and other informal material used to present the building blocks in meetings and similar Presentations Rich pictures/diagrams M2. Guidelines Guidelines describing how to use the building block, or how to update it M3. Examples
?. Process
?1. Reviews The purpose of this section is to collect review meeting minutes, comments and notes Date and participants for each review, list of comments etc.
Z. Graveyard
The purpose of this section is to collect pages from the wiki space that are no longer in use Material that is no longer valuable, except for reference just in case