SW Documentation

From AccountIT
Revision as of 11:00, 31 August 2014 by Arvinder (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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