I joined the middle of a middle size project, which runs already for several years. One of problems is that the document describing the architecture was never written. Now I was assigned a task to write the architecture description.

During the time I working on this project, I gathered all information I needed to write the document. Since I also added some features, I identified some pieces of code, which are clearly breaking the architecture as it is described.

For example, the GUI was supposed to be a thin layer, without business logic. That is what I was told. The implementation contains lots of logic.

My boss assigned me the task, to write the document describing the architecture of the system. The target audience are current and future developers working on the project. I need to describe what should be, but I also need to describe the deviations somehow.

So, where should I describe these problems? Bugs tracking software? Or should I describe implementation's deviations from the architecture in the document describing the architecture of the system?

  • 8
    I don't get it. You described the architecture based on the implementation, to then discover that the implementation does not conform to the description. Is it not then your description which is flawed?
    – back2dos
    Nov 19, 2015 at 14:20
  • 4
    @back2dos I'm interpreting this as the software tends to conform to certain architectural rules and styles, but some components break those rules and styles.
    – Thomas Owens
    Nov 19, 2015 at 14:25
  • 5
    Who assigned you the task, and who will be the audience for your document? Ask both groups what they want to read - the architecture as it should be, the architecture as it is, or both. And as we cannot mind-read the thoughts of those people, I am voting to close this question as opinion based.
    – Doc Brown
    Nov 19, 2015 at 14:44

5 Answers 5


If you are documenting a design or architecture of a system that has already been built, the document should describe it as-built and not as-designed or as-intended. If there are oddities or discrepancies in the architecture, then this document should call out those issues and explain them as much as possible to a reader.

If you are able to get information from people who have worked on the system from the beginning (or at least longer than you have), it would be useful to capture more information about what was actually intended and why the architecture and design deviated from this intention.

At the end of the day, a design document should serve as a guide to the code. If the document doesn't help a new developer understand the current state of the code base and how it is structured, than the document isn't useful.

This document should be a living document that is used to guide future planning and design of changes to the system and then updated accordingly, within your development process. As the design changes and evolves over time, the document should also help developers understand why things are the way they are at present.

If you are looking for advice on capturing the architecture, I like the approach advocated in IEEE Standard 1016-2009 IEEE Standard for Information Technology - Systems Design - Software Design Description. It provides a reasonable structure for a design description, which can be used to capture both architectural and detail level design information.

I would also consider these deviations to be a form of technical debt. It may be a large undertaking, perhaps even a small project, to fix the issues, I would recommend making the existence of the technical debt more visible. If that means you use your defect tracking tool, then you can put one or more issues there. If you have another tool that you use for tracking suggestions and enhancements to the software, that may be another place to put it.

  • 1
    I think you misconstrued his question which is asking about how to outline and communicate the intent of the architecture vs. the actual implementation of it: Should they be in the same document, separate documents, etc? I don't see an answer to that question clearly defined here. Nov 19, 2015 at 14:38
  • 1
    @JimmyHoffa Actually, I think he answered the question : "Put it in the document describing the architecture". I guess as a separate chapter, or a subchapter in each chapter describing components. Nov 19, 2015 at 14:44
  • 2
    Eeeek... $90 >_< Nov 20, 2015 at 1:52

When formalizing the architecture of the system it is important that you understand not only the value behind what the architecture will bring to the table, but also to understand and appreciate what it should be.

The primary goals of Software or Technical Architecture is to identify the Non-Functional requirements that are realized by the Quality Attributes that will drive the System Architecture.

On Non-Functional Requirements:

A non-functional requirement is a requirement that specifies criteria that can be used to judge the operation of a system, rather than specific behaviors. They are contrasted with functional requirements that define specific behavior or functions. The plan for implementing functional requirements is detailed in the system design. The plan for implementing non-functional requirements is detailed in the system architecture.

Broadly, functional requirements define what a system is supposed to do and non-functional requirements define how a system is supposed to be. ... Non-functional requirements are often called "quality attributes" of a system. Other terms for non-functional requirements are "qualities", "quality goals", "quality of service requirements", "constraints" and "non-behavioral requirements"

Of course identifying the architecturally significant requirements makes sense when on a greenfield project, however when working with existing software, it is best to be as disciplined as possible. You will not want your software architecture to be influenced by the existing system.

Software architecture to be authoritative really needs to be 3 things.


This is the part of the documentation where you declare NOT WHAT IS, but how things SHOULD BE. We do this through the use of various Architectural Views of the system. We define the components that should be, how they interact, and then we optionally drill down into each component for more granular views that declare how the system should be designed.

This is an important distinction. The System Design should be constrained by the System Architecture, they are in fact separate but related things.


The Rationale of your Software Architecture is what provides legitimacy and authority to the architecture decisions that were made. Perhaps the decision was made to utilize a Pub/Sub event listener over MQ for triggering a batch job and you diagram it?

Why was this decision made? We explain why in the Rationale section and link back our explanation to Non-Functional Requirements, Quality Attribute Goals, or Architecturally Significant Requirements. (Eg. Jobs must be asynchronous and repeatable, Maintainability as a quality attribute drives that in the event of a batch job failure that jobs can be re-initiated via an MQ message, The System must have Zero Message Loss with asynchronous communication, etc...)


Now that you have declared how architecture should be and proved it with your Rationale, you can now identify Risks on the current state of the system to where this doesn't abide.

(Eg. Server side validation is being duplicated on the client side Javascript code. This is a violation of the DRY principle and this runs counter to the Quality Attribute of Maintainability. There are no Non-Functional requirements defined around Performance in this area so there is no Rationale for the current system behavior)

Your Risks can also diagram where current state is currently deviating from Architecture. These Risks can be addressed by the development team now, either through their project plan or by adding this into the backlog.


You really do need to decide whether you're supposed to be documenting the current structure of the project, or the desired structure of the project, or both.

You could document the goal, for the purpose of guiding future development along the desired lines, and raise the deviations as bugs (perhaps link to these bugs from the relevant parts of the document). Or you could document the reality in order to provide an introduction/overview to the code. Or you could document both side-by-side, so that you simultaneously have a guide for future development and an accurate description of the current code in one place. All are reasonable depending what the document is supposed to be for, so I don't think we can usefully tell you which one to do.

You should also bear in mind that the desired architecture might not be universally agreed among those involved (either because they want different things, or because some of them have realised that some original shared desires were impossible or impractical and therefore resorted to writing the existing code that deviates from the goal). So you also need to know whether or not you have authority to decide what's desired, and if not who does. The existing structure does at least have the virtue that there's only one of it to document!


Write in the architecture design document what was supposed to be, and for each conflict you find open a ticket in the bug tracker describing the conflict. The ticket's comments section will offer a platform for the relevant people to discuss that particular conflict.

Note that the resolution of each of these tickets can be to change the implementation to match the design - but it can also be to change the design to match the implementation. Ideally the former is preferred, but sometimes there are technical and/or business constraints that makes it more efficient/pragmatic/possible to choose the later. In that case, it might be a good idea to refer to the ticket from the architecture design document, so that future readers who don't understand why that particular inferior design choice was chosen can read the discussion in the ticket and understand the reasoning behind it.


I would be inclined to write an architectural document organised into 3 main sections.

The first introducing the design/architecture that was initially intended. This will allow new developers/readers to get an idea for what the system is supposed to do and should obviously be tied to the requirements/usecases etc.

The second section should explain very clearly exactly what the architecture actually is. This allows the new developers/readers to get an idea of the current state of play and what they are dealing with if they look at the software (and potentially other documentation). This section should clearly indicate the difference between what was intended and reality as this will most likely hightlight things that are either very wrong with the original architecture (hopefully not too many!) and areas where shortcuts/hacks (probably a fair few if there was a large degree of pressure on the dev team) have been made and requirements are not being fulfilled or the software is beggining to look 'poorly' designed i.e fragile, instable, un-portable.

Finally I think a section detailing the recommendations for what needs to happen now. This should be any changes to the architecture/design and a roadmap for changes to the software at present in order to make your vision become a reality.

I think this covers (at high level) what needs to be captured. How you do this in terms of the subsections of the document or bug tracking software you employ is down to the domain you are working in/personal preference/team size/budget/time scale etc.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.