Intro - Observations from network documentation
I have worked in the IT field for almost 30 years, with the last 20 years as a network infrastructure and service architect. I have read and written several different network documents, and I think the most important of them is the network architecture document. But what makes a good architecture document?
Many people working in the IT sector have certainly encountered a situation where they have built an environment by ordering load of hardware and then started to build an environment without a proper plan.
Of course, the existence of a plan is not a guarantee for creation of a good environment, but a good plan is, on the other hand. Too often, I have read documents that focus only on the description of the technical implementation of the environment, which does not describe the basics of architecture or even the services that the environment produces. The technical description of the environment is, of course, an important part of the network documentation, but it should be the last part of the architecture description.
The stages of an architecture plan
Through my experience, I have found a way to ensure that the network plan contains everything necessary. I'm sure that every network architect has his/her own design phases that suit him/her. I have found this phasing to work for myself:
1) Preliminary data collection – Knowing the starting point of the environment gives a solid starting point for the network documentation.
2) Definition of requirements - This is absolutely the most important phase of the architecture planning process. This phase sets the baseline for the architecture.
3) Definition of services – This phase explains what services the planned environment will produce for users.
4) System design – Opens the design and environment topology.
As you can see from the list, only the last step defines the topology of the actual solution, which technology will be used, and the detailed specifications of the implementation.
Preliminary research - the most important step
The most important part of architectural design is to find out what the environment is being built for and what are the requirements for it. The purpose of research is to find answers to the questions:
- Who or which groups are the most important stakeholders in terms of the service?
- What services the environment is supposed to provide?
- Which requirements the service must be able to meet?
A good additional question to all the questions above is 'why'. The architecture document must be able to answer why a service or requirement exists. In the research phase, the most important thing is to find answers to the above questions, not to find answer to technical solution.
What makes a good network architecture document?
A consistent structure in an architecture document cannot be overemphasized. A good structure gives the reader an overall picture of what, why and how the environment will be implemented. When writing a document, it is important to understand to whom the document is aimed at.
In my own architecture documents, I have ended up with a structure where the story goes:
1) Presentation of the documentary
2) Design principles and requirements
3) The services to be produced
4) System topology
5) Detailed specifications of the solution
6) System management.
The introduction of the document briefly describes what the document is about. This part also describes the limitations and dependencies that are covered in the plan.
The principles and requirements are the core of the plan, which opens the reasons for architectural solutions on both functional and technical grounds.
The services to be produced list all the functionalities that the system to be built will produce.
In the system topology, the overall architecture is opened for the first time, and the components of the system and their dependencies are described at the top level.
In the details of the solution, the technology used to build the system, and the detailed specifications of the solution are described.
System management describes how the continuous services of the system are managed. This part is an important part of the documentation framework in terms of the next step, when the system’s operational guide/runbook is documented.
It is important to keep all the stakeholders involved throughout the process to ensure the document meets their needs. Another very important phase of the documentation is to keep the documentation up to date. Regular reviews and updates keep the documentation relevant.
Over the years while I have been working as a network architect, I have found these best practices work for me. I have written hundreds of network architecture documents, and I have received good feedback from the stakeholders about the structure and storyline of the documentation.
Summary
If there is the one thing that IT architects should remember from this text, I hope it is this: whatever You are planning, hopefully the technical implementation is Your last step of the planning process.
All feedback about this, my very first blog, is appreciated. If this article is of interest to others in the community, then the idea is to open my network design process in more detail in the following articles. Stay tuned.
