Standard Practices for Documenting High-Level Software Architecture

Architecturedocumentation

I am an amateur developer and all my programs up to now were simple enough to be documented within the code. While reading the code it was clear what I was doing such and such action (my standard test was to look at the code 6 months later and understand everything at first read – and I have short memory span).

I am now faced with a program which is outgrowing my capacities to remember the various interactions between

  • the code itself
  • the indexes in the database
  • the interactions between various modules ("worker" core code and "library" ones)

My current documentation is a whiteboard where I have all kind of boxes and arrows which point to code, to database indexes, to actions being executed, to state change etc. Just for reference, a fragment of the mess:

enter image description here

My question is whether there is a standard, or named set of best practices (named in the sense that this is a set of practices which were grouped under a specific name) for the documentation of more complex products.

What are the keywords I should look for (general attempts at "document software architecture standards" and similar variations usually led to software for workflows or building architecture CAD systems).

I also expect that there may be no general best practices for high-level descriptions and that everyone builds its own philosophy.

Best Answer

There isn't one standard that everyone adheres to. Software projects can vary greatly (think: helloworld.py vs the code in the space shuttle).

One very common method is to use the 4+1 model. Instead of trying to cram everything into a single style of document, this methodology breaks the design into five components:

  • The Development view
  • The Logical view
  • The Physical view
  • The Process view
  • Scenarios

The various views describe the product from four different perspectives. The scenarios are where the use cases live, and describe the interaction of the other views.

Note: This is a conceptual model, and is not tied to any specific tool.

You can read more here:

  1. 4+1 architectural view model (wikipedia)
  2. Architectural Blueprints—The “4+1” View Model of Software Architecture (IEEE paper - pdf)