Building out the Simple Software Architecture movement…

Yesterday I expanded my concept of architectural simplicity. I’ve placed that initial thinking into a table and started building out some guidelines for the documentation.

Document Variations Guidelines
Requirements Can be presented in a number of different ways but servers as the guide for creating the rest of this documentation.
  • Detailed listing of the requirements both perceived and actual.
  • Listing of functional and non-functional requirements.
  • Mapping of requirements to the technology to be deployed.
  • Mapping of that technology to components of the reference architecture
  • Clear and easily traceable matrix (traceability)
  • Changes to this document should force changes to all documents except the reference architecture.
Vision Document This document should contain the initial thinking around what is to be built and deployed as well as the long range vision of the project.
  • Vision document should include the overall high level vision
  • Overall high level scope
  • Funding requested
  • Budgetary report against funding
  • Modifications of this document result in versions.
An Architecture document: Represents the solution being developed, deployed or managed.

What will be deployed (projected) This is a static document

Documentation of any and all changes (separate document called deployed solution) this is a living document

  • % variance from reference
    (the higher the % the more likely you will have issues later)
  • No more than 10 pages
    To reduce page count link to a presentation with the graphics in that.
  • The vision and scope for the project should be separate.
  • Modifications of this document result in versions.
A reference Architecture: The basis for a new solution from existing technologies. Simply linked to in the document above. Updates to the original reference architecture should documented in the Deployed Solution document
  • Depending upon the publishing organization this can be huge (50 or more pages)
  • Leave as is, don’t modify anything except your deployed solution map
Solution Map This shows the relationship to the actual physical reference architecture diagram
  • Solution maps are living documents that show where things are actually deployed (under someone’s desk and in a closet in Topeka KS etc.).
  • This document is a living document modifications result in new versions.
Operations Guide: How the technology should be managed by the operations team.

How the solution should be operated mapped to ITIL or Service management framework specific to anything required by the overall solution. Maps back to the Architecture documents. This is a living document.

  • The overall Ops Guide should directly between the deployed solution and the overall ITSM of the organization.
  • Variations of standard operations procedures (different than the vendor reference architecture) should be noted.
  • This is a living document and should be incremented whenever versions are updated.
Operations Manual: The step by step guide to complete core processes.

Modified when reference architecture or deployed solution guide changes. This is a living document.

This is the hit by the bus document for the administrators. The better this is maintained the lower the risk the organization had if someone leaves.

  • Step by step process should be documented and updated whenever the process changes.
Server book: Everything about the physical or virtual servers that comprise a solution (memory, hard drive) Should include a server log (who changed the server and why) as well as updated frequently as components are changed. This may include the parameters for this solution in AWS, and then if moved to a new CSP that parameters for that solution as well.
  • Any change to physical, logical or virtual servers should be maintained for future consideration.
  • This document is the most living of the documents in this system and should be updated whenever the server has any modification at all (patches, hardware changes and documenting issues). A direct feed from the service desk tagged for this server is the quickest way to build a server book.





















































Total page counts and other components will come later. For now the first two documents should be tight less than 10 pages each. If needed based on organizational rules the financial components listed in the Vision document can be moved to their own document.

Getting to simple while appearing to be hard in the long run reduces the risk of deployments and allows for managed change in an organization. It also supports the concept of replacement where people can go on vacation or leave the company and their functions can be replaces.


Scott Andersen

IASA Fellow!