Architecture Documentation Checklist

When creating business IT documentation (e.g. IT architectures/designs) following these rules will help for producing sound documentation:

  1. Documentation should be written from the point of view of the reader, not the writer.
  2. IT Documentation should be organized for ease of reference, not ease of reading. A document may be read from cover to cover at most once, and probably never. But a document is likely to be referenced hundreds or thousands of times.
  3. Avoid repetition. Each kind of information should be recorded in exactly one place. This makes documentation easier to use and much easier to change as it evolves. It also avoids confusion.
  4. Avoid unintentional ambiguity. In some sense, the point of architecture is to be ambiguous. However unplanned ambiguity is when documentation can be interpreted in more than one way, and at least one of those ways is incorrect. A well-defined notation with precise semantics goes a long way toward eliminating whole classes of linguistic ambiguity from a document. This is one area where architecture description languages help a great deal, but using a formal language isn’t always necessary.
  5. Standardize your documentation. Use always the same templates for the same documents within your organization. Even better: Make use of de-facto standardizations that also make sense for people outside your organization, since you will be working with many people outside your organization during the life cycle of your product. A standard organization offers many benefits. It helps the reader navigate the document and find specific information quickly.
  6. Record rationale. So document decisions made. Recording rationale will save you enormous time in the long run, although it requires discipline to record in the heat of the moment. It will prevent the same discussions over and over again and everyone knows why the chosen path is taken.
  7. Keep it current. Documentation that is out of date, does not reflect truth, and does not obey its own rules for form and internal consistency will not be used. Documentation that is kept current and accurate will be used.
  8. Review documentation for fitness of purpose. Only the intended users of a document will be able to tell if it contains the right information presented in right way.

Architectures References

The field of business IT Architecture is covered with many many methods, foundations, industry organizations and reference architectures. So whatever the specific domain you are active in use and re-use information already there as described a solid reference architecture.  And do not forget: When you publish your architecture document on the web, make sure to use a common creative license, so others can improve, reuse and build upon your work.

Link Categories Overview
Architecture magazines (6)Architecture Methods (12)Architecture organizations (16)Architecture Patterns (2)
Cloud (4)Example Architecture (1)Foundation Architectures (3)Guidelines (2)
Industry Architectures (6)Microservices (3)Mobile (1)Principles (4)
Reference architectures (37)Security architecture (8)Software Architecture (2)Standards (6)


Architecture checklists

An architecture checklist helps in the governance process. Architecture checklists can become long, complex and time consuming in usage. However the aim with this architecture checklist is that it will help you and all your stakeholders involved in a simple way when you are dealing with architecture quality and risk aspects.

This architecture checklist is composed out of some critical questions that all relate back to the main goal of doing architecture in the first place.

Simple architecture checklist questions:

  • Is your main goal covered and reached with this architecture?
  • Does the architecture address operability?
  • Does the architecture address the following quality attributes:
    • performance
    • availability
    • maintainability
    • modifiability
    • security
    • privacy
    • testability
    • operability
    • flexibility
  • Does the architecture address and use principles? E.g. business principles.
  • Can implementation risks easily be derived out of your architecture deliverables?
  • Are architecture reviews done in a structured way? Architecture reviews SHOULD be performed to increase quality, control costs and reduce risks.
  • Is it clear what assumptions are used for your architecture? (Take explicit and implicit assumptions into account!)



Serverless Architecture

Staying up to date in the complex field of business IT trends is hard. Since I felt my knowledge of the  AWS (Amazone Web Services) Cloud portfolio was no longer up to date I was happy to have the opportunity to visit the 2016 AWS Global Summit organised on the May 24 in the Netherlands. The number of visitors that this AWS Summit attracted was far beyond my expectations. But since this was my first AWS Summit experience I did not really know what to expect of course. Continue reading “Serverless Architecture”

Rapid Application Development and Architecture

Programming web applications and creating IT systems has long been a complex and slow job. Following the usual software engineering life cycles the development phase could not start before requirements were written, architecture was approved and a lot of Unified Modeling Language (UML) diagrams were drawn. So even before the project produced something of value tons of documentation was produced.

Due to the success of agile software development methods as e.g. scrum and devops often architects grown up with traditional development approaches, are experienced as a barrier for speeding up. So the role of traditional IT architects and architecture for creating solid design documentation has become under immense pressure. Continue reading “Rapid Application Development and Architecture”

How Security Personas will help you

One of the tools of IT architects and UX designers is to work with so called ‘Personas’. Personas are fictional characters created to represent the different user types that might use a system, website, product or service. Using personas is common practice when dealing with UX design. But when developing a security architecture for a new system, service or website security personas are also valuable to use. Security Personas force you to think different about the goals and behaviour of attackers that are going to hit your system. Continue reading “How Security Personas will help you”

Complex attack vectors

Good security is goal oriented. A good security architecture is tailored to your situation.
When defining a product or new (IT) service one of the key activities is to define your specific security requirements. Defining requirements is known to be hard, time consuming and complex. Especially when you have an iterative development cycles and you do not have yet a clear defined view of your final product or service to be created. Continue reading “Complex attack vectors”