A frequent problem in maintaining legacy systems is understanding why things are the way they are. It's necessary to incorporate the thinking of the developers at the time, understand the development context, their creators' knowledge, and the political scenario of the responsible organization. This makes it difficult for the developer/architect to maintain a standard and perform system maintenance in a clear, cohesive, and sustainable way.
The Philosophy of Purpose in Actions
In my personal view, when we do something, it should have an objective reason for being done. This reason can be logical, a leap of faith, religious, emotional, or a desire, BUT THERE MUST BE A REASON. When we do things without a clear purpose, we are making random decisions that lead us down an unknown and poorly planned path. We allow "randomness" to make our decisions, causing us to lose control of our lives.
Applying "Purpose" to Software Development
If we apply the concept of "having a purpose" to software development, we can extract the idea that in an ideal system, each decision made throughout its lifecycle must have a clear reason, from its conception to its continuous maintenance. The decisions made should guide the solution toward a planned scenario, based on clear requirements and controlled by good software engineering practices, where each micro-decision builds a movement that leads the system to its current state. In this state, it is expected to contain characteristics such as maintainability, clarity, intuitiveness, and well-defined rules, with details postponed as much as possible to facilitate eventual changes.
Toward the Solution
If each step in a software's lifecycle is important to understand its direction, how could a newly arrived developer/architect in an organization, without contact with its creators and maintainers, understand these small decisions made over time without relying on deduction? The answer is obvious: documentation. Okay, easy. But what should this documentation be like?
Why Not Bureaucratic and Technical Documentation?
Common documentation is usually surrounded by requirements that give it a quite different purpose from our objective.
1. Continuously Updated Documentation
In standard technical documentation, its constant updating and evolution are necessary, as it follows the system, which follows the business model, which constantly changes. But does the documentation we're looking for need to be like this?
If what we seek is to trace a chronological line that allows us to record decisions made and their reasons, it doesn't make sense to require this list to be updated, as decisions made in the past cannot be altered, only corrected in the present. So, we need documentation that doesn't alter information recorded in the past. Check!
2. Documentation with Correct Concepts
When we read technical documentation, we expect its records to be consistent with the presented concepts and their correct syntax. But does this matter for our objective?
Documentation that records system decision-making doesn't necessarily need to be correct. I know, it seems strange, but let's discuss this.
If, during the development of a legacy system, those responsible at the time made a wrong decision due to a lack of knowledge or technical immaturity, this cannot be corrected in the documentation, as it would impact the macro analysis that allows us to understand the current situation of the system. "If we want to understand how a person acts, we must think as they think."
Alright, so we can already consider that our ideal documentation cannot be updated due to incorrect information, but it still makes sense to create a field for errata, which records the incorrect information considered along with the argumentation of why they are incorrect.
3. Documentation Without Prerequisites
Standard documentation usually requires its readers to seek a foundation so that some abstractions become clear during their study. Let's exemplify: the React framework documentation requires a prerequisite of understanding the JavaScript or TypeScript programming language, as it uses both for its development. But in our ideal documentation, should there be prerequisites?
If the main idea is just to allow the reader to "think as the developer thought," it doesn't make sense for it to be in technical language that requires the reader to have deeper knowledge about some topic, as in this case, it would be changing its proposal from being just a record of decisions made to becoming a technical manual of tools and techniques.
Amazing! So our ideal documentation should avoid being technical and prioritize only the argumentation of why to do something in a certain way.
A Real-World Analogy
Let's imagine that we write a diary. This diary aims to record our lives, thoughts, and events. We don't erase already recorded stories because we want to keep the memory. We frequently note things we judge "not so expressive," but over time, we realize they are valuable information. When we note something, we don't expect to need to remember external contexts when rereading in the future—we write the contexts to facilitate our later understanding. Writing in a diary usually has a "therapeutic" effect on our minds, as it makes us reflect on who we are and why we act.
The reality is that the diary is something natural, that flows smoothly and shouldn't be seen as an obligation, but rather as a way to group thoughts, events, and decisions of our life so that we can reflect, remember, and avoid the same mistakes from the past. We would like our documentation to be the same way.
How Then Should This "Documentation" Be?
We raised a series of requirements from standard technical documentation to compare them with our need in the proposed model, and through them, we understood that we would need to make some changes. But which ones?
- Records must be readonly: Documentation should only be written and not altered, allowing events to be recorded with their contexts and thoughts, with a brief explanation of why something was done as it was, but it should never be altered.
- There must be an errata: Documentation should allow technical errors to be highlighted with their respective explanations so that no one interprets something wrong as right or right as wrong.
- Must not require prior technical knowledge: Documentation should not require technical knowledge as a prerequisite for the reader to understand its content, as it would lose its proposal of being a record book and become technical documentation.
- Its writing should be something natural that provokes critical thinking: Writing documentation should not be a burden. It should just be the record of thought, context, and reason why actions were taken during the development and evolution of a system.
A Discovered Model
We did it! We created an ideal model to record decisions made in our applications that is light, intuitive, and useful.
Decision
- Title: Use of a centralized library to utilize resources common to all applications
- Decision Date: 05/01/2025
- Decision Type: Architectural
-
Description:
- Context: Several APIs would need to be created in a short interval and often with parallel development. All of them would have common resources that could be reusable.
- Motivation: It was necessary to reuse various solutions for all projects.
- Details: It was decided to centralize a library with reusable functionalities not linked to business rules to be used by all newly created APIs, where they will be constantly updated (there will be a routine process to update this library in all systems). Among its functionalities, the adapter that allows HTTP APIs to communicate with legacy WCF systems will be included.
- Responsible: João das Couves, Jhali Rheinviei, Tsujiro Kisidane
Errata
- Original Decision: Use of a centralized library to utilize resources common to all applications
- Errata Date: 02/10/2025
- Error Description: During development, we understood that it would be very costly to maintain the WCF services reference within the legacy adapter, as each service update would require uploading a new version of the library.
- Correction and Reason: It was decided to separate the legacy WCF services reference from the adapter within the library, now passing the reference to each application that will manage it themselves.
- Responsible for Errata: Tsujiro Kisidane
Final Thoughts
Well, finally, I think we achieved the objective proposed at the beginning of the article, right? Maybe you think the idea is incredible, maybe you think it's incredibly pathetic. Maybe you know this idea from a real author or another person who has already recorded this idea.
The truth is that this is just a sharing of an idea I had when reflecting on the difficulties of maintaining a system where you need to delve into why it is the way it is to understand its purpose. I didn't stop to research if content like this already exists or if any author has already proposed this idea. I just thought, wrote, and posted 👍.
Anyway, I hope this dubious content has added something to your life. See you soon, my friends.
Top comments (0)