Thoughts on Evolving a Software Architecture

Hello reader, today I have some thoughts about software architecture and how to approach making changes to an organisation software architecture. The thoughts I have are a result of some of the pain I’ve gone through working on software throughout my career.

Documentation

What tends to happen with software documentation is that different teams will have differing levels of effort when it comes to documenting their areas of responsibility, resulting in documentation quality and consistency becoming poorer over time.

To ensure the quality and consistency of documentation I’m of the opinion that the documentation about an organisation’s software systems is the responsibility of the lead software architect. One of the responsibilities of a software architect is to ensure that the entire software stack is coherent and current and thus they are best placed to not only document the what but also document the why. Additionally, an architect regularly reviewing documentation will have ample opportunity to discover areas of improvement just from noticing parts of the documentation that seem weird.

If an organisation also has technical writers in their employ I would advocate that they report into the software architect. This way the architect can oversee the documentation written and ensure quality is consistent.

Flexible Software Architecture Decisions

If an architectural change is enforced with little prospect for the change to be altered or debated by those who are implementing the change, then this can lead to resentment towards the one requesting the change. Often times the ones requesting the change are not present to help when difficulties arise as a result of the change which can lead to comments being passed around like

• “this change has created a whole bunch of work for us and doesn’t bring us any benefit”
• “this change is a waste of time and money, we already have something that could do the same thing”
• “solving issues has gotten so much harder, why do I have to give up my after hours work time to fix this nonsense?”

If changes are not well received but the architectural change is actually necessary, then I think there are generally two reasons why:

• There is insufficient or poor quality documentation on the architectural change. This means that everyone who needs or wants information about the change is unable to find the information that they’re looking for in a timely manner. See my point about documentation above!
• The architectural change is probably incomplete, in that there are additional changes required to make working with that specific change more pleasant. I’ll elaborate on this in the next section.

So if you are in a position at the top of your organisation and you are considering making software architectural changes, I would highly recommend that you engage with the engineers working under you as they will have valuable day to day insights that will help you in your decision making. As a bonus, any changes you put in place will be better received by your colleagues.

Software Lifecycle Aware Architecture Decisions

One of the things I see commonly with some architectural changes like “move to cloud service providers” is that the change specified by the person making the decision is incomplete. As a result, other engineers are left trying to figure out what else is required to make the change possible.

I think this is best illustrated with an example. Let’s say that an architect has decided that in order to keep things consistent some services should be replaced with managed AWS products. The architect compiles a list of services that are to be transition to AWS and directs the engineering teams to make the changes. However the directive is missing the following:

• How to develop locally against an AWS deployed service
• Deployment of changes to AWS
• Monitoring and troubleshooting of AWS services

What tends to happen is that the engineering team will try to fill in these missing parts but run into difficulties (such as access rights, difference in environment between local and AWS etc) and become frustrated that a lot of time is being wasted on the transition which could have been used to do bug fixes or feature changes. It’s also likely that the difficulties are solved in several different ways by different teams and that these solutions become tribal knowledge and not well documented.

Now if the architect above had also investigated and documented…

• How to transition the services to an AWS deployed service
• How to setup a local environment that is a good stand-in for the AWS service
• How to deploy changes to the AWS service
• How to investigate errors that occur when the service is deployed into AWS
• How to effectively monitor the AWS service

… then the engineering team would have a lot easier time switching to AWS. An architect doing this upfront investigation and documentation would also need to consult with the engineering team, which gives the engineering team an opportunity to provide feedback on the transition.

So I think any architectural decisions need to also consider what the change means in terms of the full software lifecycle from development to production. Otherwise the changes that occur can become disjointed as different teams try to address various difficulties in their own way.

So these are some of my thoughts about software architecture. In summary, good documentation, flexible decision making and considering the full software lifecycle will ensure that any software architectural change is well received by everyone in an organisation.