You need to design a new solution for a complex IT system. What are your actions?
Before starting to develop an action plan, all best practices from managers and specialists should be combined into a clear (at least in parts) diagram.
The example below shows a diagram that explains that there must always be one factor at the forefront. This is the first brick that will define the format of the entire work.
When developing software, I propose taking a GitLab or GitHub server as such a brick and Markdown format as documentation located in one place and implying work with it as code. I suggest taking it and never changing it. Because documentation in any project is your everything (we won’t return to this more - it’s customary).
→ The risk of documentation becoming outdated as the product develops or evolves is minimized in such a scheme. The main reasons for information being outdated are:
→- Documentation is not written by anyone
→- The documentation has spread and it’s impossible to gather a complete, up-to-date version from fragments
Both of these factors are kept under control in the specified scheme.
In some teams there’s a chance for a community to emerge, where employees develop the direction of personal contribution to documentation independently.
Three forces must go parallel: this is the architect, specialist and project curator.
The specialist needs to perform tasks assigned by the architect. Specialists of different levels independently find a solution. The architect defines the format for describing the project. And the project curator takes care of roles and rules so that work goes smoothly, predictably and as comfortably as possible.
Without clear delineation of responsibilities on both the software developer’s side and the customer’s, the work will be inefficient.
This topic is an introduction to the Gemba approach – tracking workplace processes.
——-
You should start working on a large project with a high-level diagram (I remind you that the brick in the form of git+markdown was laid earlier). It allows everyone involved to speak the same language and avoid misunderstandings and explaining things at the elbow.
At each stage, employees from various departments and specialties are involved.
A common approach among customers is visualizing the architecture of the software “C4 Model” (Si-Four: Context, Containers, Components, Code) and its variations.
Diagrams of different levels are detailed differently, so they are understandable to both technical and non-technical specialists.
In my work I use:
- GitLab: A platform for collaborative software development. We utilize it for version control, issue tracking, and project management.
- Markdown: A lightweight markup language used for formatting text documents. It’s a simple and readable format ideal for documentation.
In the diagram below, I’ve outlined key components and processes involved in designing and implementing this solution:
- Core Solution Card (GitLab): This represents the central repository where all design elements are stored using Markdown formatting.
- Processes: The sequence of steps required to develop the solution.
- Regulations: Rules, guidelines, and standards that govern the development process.
- Responsibility Zones: Clearly defined roles and responsibilities for each team member.
- Interaction Scheme: A diagram illustrating how people interact on the project, considering task types and their sequence.
- HLD Diagram (High-Level Design): This provides an overview of the system architecture and key components.
- Deployment Diagram: Details the infrastructure and environment required to deploy the solution.
- Container Diagram: Specifies the containers used, their configurations, and interconnections.
- Online Documentation: A centralized repository for all documentation related to the project.
Always follow the diagram blocks. Find matches and build the work so that there are no white spots. If changes are needed in the process, make them gradually.