Why do we even need any documents in the development process? What about this statement that the ? code documents itself Let's consider the most common scenario: the system's code (be it a program, project, or product) is being written over a long period, and the team gradually changes during this process, taking certain knowledge about the system with them as developers leave. What can we do in such a case? The simplest answer is to that captures all the implementation details to ensure the system meets the original requirements. write a specification However, such a document is very difficult to write in advance, and during the development process, some implementation details may change (adapting to the market/new requests for mechanics, etc.). So, what can we devise to improve the ? bus factor Let's try to follow a flow that could be one of the possible solutions to address the problem mentioned above. Requirements & RFC First, we need to describe the initial design based on requirements from stakeholders and document it. After that, this document can be shared with other teams and their feedback requested: ask to implement certain features, comment on the initial design, fix a certain interface, etc. Such a document can be called an . RFC , or "Request for Comments," is a document distributed among interested parties—including developers, architects, and other teams—to collect feedback, comments, and suggestions. It is less detailed than a specification and includes only the initial problem, task, and solution domain. Being more flexible, it allows for actively accepting changes in the design ensuring a deep understanding of the task and facilitating quality and thoughtful decision-making. RFC Design Commitment & ADR Okay, we've and . What's next? defined technical requirements gathered requirements from other teams At this stage, it's necessary to and all the main functions it will perform. For this purpose, we write an . finalize the system design ADR , or "Architecture Decision Record," is a document that records important architectural decisions made during the software development process. Each describes a specific high-level architectural decision, its context, alternatives considered, the decision made, and the motivation for choosing these specific details over others. ADR ADR Such a document allows every team member (and other teams as well) the principles and values that underpin the design. If a new developer joins the team years later and asks, "Why did you do it this way?", they can be shown this document, which will answer all their questions. to understand Specification Now it's time to write the code and its specifications. At this stage, we thoroughly work through each feature, simultaneously compiling all the information and implementation details into a special document. This document should reflect the current low-level requirements for the system. : during the software lifecycle, such a specification can change significantly, and that's okay. However, it's very important to still stay within the original design and architecture to prevent the codebase from becoming something unmanageable. An important point Test plan Why is it needed? It is critical for a test plan to be built that was written according to the specification (we write code and tests for this code so that they pass), but on that includes critical scenarios that . It is also very convenient that you can submit such a test plan for review to other teams (for integrations or just for additional testing), making it clear how the system will behave in different situations. not on the basis of code the basis of a design must be processed correctly What does it include? All possible system operation scenarios Happy path Sad path Error handling All possible invariants that must be maintained during system operation Acceptance tests to check the system state at the start (should consider the environment, e.g., data on the network) We've finalized the , written the code and , and compiled the . Sounds pretty solid already! But what else could we add? design specification test plan Deployment Plan Such a plan might be needed to some extent to and create conditions in which any team member can deploy the system and verify it's state. improve the bus factor Why can't we do without it? We can, but in the real world, large teams where many people are responsible for different parts of the system, and the deployment process might be to DevOps. What's wrong with that, since we've written tests, put them in CI, and checked for vulnerabilities, do we need anything else? Maybe not, but often tests do not consider the current state of the system and test not quite what we would like. fully delegated What deployment plan : might contain A complete description of actions that need to be performed for the deployment to take place Deployment parameters: Environment variables Initial state Parameters for launch A plan for if something goes wrong at any step A backup plan, if possible The necessary state to which the system must be brought in case continuing the deployment is not possible Actions that need to be performed after deployment Notify other teams Enable necessary integrations, if needed Nothing complicated, right? Having such a document for a specific update can significantly and on specific individuals. Isn't that what we want? improve the bus factor prevent reliance Conclusion In the software development process, it's important not just to write code, but also to create documentation that ensures understanding and consistency throughout all stages of development. The documentation , but experience has shown that documentation is very important to maintain the quality, stability and future scalability of the system, especially when the team changes during development, and also when the project evolves and adapts to new requirements. may be the code itself Documentation includes (Request for Comments), (Architecture Records), , , , and more. This will guarantee the , simplify the process of into the project, and . RFC ADR Specification Test Plans Deployment Plans retention of knowledge in the team integrating new employees increase the overall reliability and resistance of the system to changes
