preface

In project management, it is inevitable that technical documentation will be involved. When discussing documents, it’s common to get caught up in the “yes” or “no” choice. And they’re ignoring how to minimize the technical documentation and still maximize the value of the documentation.

Reading an article by a CTO, I realized that we might be starting from the wrong place. Many projects have shown us the power of documentation as we take it for granted.

In order for developers to quickly learn about a project and for new entrants to take it on quickly, there are usually three types of documentation provided in a project: README documentation, architecture documentation, and API documentation. Let’s take a look at what they typically consist of.

The README document

If you look at GitHub’s open source projects, they all contain a readme. md file, which is the README document. This is also the file that is created by default when you create projects on GitHub.

This is also the first document you see when reading the source code. If you don’t have a README document in your project, or if it’s empty, you need to rethink it. The README document makes it easy to describe the structure and basic operations of the project for team members or for future participation.

README documents typically contain the following:

  • A high-level overview, at least three to four sentences describing the purpose of the project;
  • Project CI and quality assurance;
  • Operational requirements, such as programming language, tools, environment configuration, etc.
  • Construction specification;
  • Local run instructions. This usually includes instructions for executing each step of the command or a Docker container-based run.
  • Configuration description. Key configuration instructions that developers need to understand, such as changing port numbers.
  • Associated critical services. Examples include CI services (Jenkins, GitHub, etc.), project management tools (JIRA, etc.), prototyping tools, etc.

Take the open source framework Nacos, for example. Part of its READM document reads as follows:

It was obvious from the beginning what Nacos, an open source framework, could do and provide.

Describes how to do this and how to start the deployment.

This is followed by associated projects, documents, associated repositories, and so on.

From the above instructions, we basically know what Nacos is for, how to do it step by step, and how to find relevant materials, documentation, class libraries, and so on. A simple document that can be very helpful to users or developers.

Architecture documentation

Architecture documents usually describe the project at the system architecture level, making it easy for anyone who wants to understand the technical details and architecture of the project to view. Architecture documents usually cover architectures and details that don’t change very often.

For architecture documents, they typically contain the following:

  • Constraints. Any business or technical constraints encountered in designing the system and indicate how these constraints affected the system design;
  • Non-functional requirements. The most important quality indicators needed to achieve business objectives;
  • Architecture design. Which architectural designs can be met based on quality metrics;
  • Solution context diagram. The system implementation as a black box, mainly shows the user role and external integration and the direct relationship between the system;
  • Solution container diagram. Show which components are made up of in the system architecture, what kind of relationships are among them, and also show which libraries or services they depend on;
  • Technology stack and version information. Presents the core technology stack and version information used to build the system, and why you chose to use them.

Documentation is part of the project and should be reviewed and iterated just like code. IO is an open source drawing tool.

For architecture documentation, here’s an architecture diagram for an open source iot project called JetLinks:



After reading the architecture and equipment access flow chart provided by this project, have you suddenly understood the architecture and functions of this system from a macro perspective? If our system also provides similar architectural documentation, it would be a great benefit both to the authors themselves (which will be forgotten over time) and to other collaborators and new entrants.

The API documentation

As for API documentation, it goes without saying that it is essential for both a front-to-back separation project and a project that provides an interface externally. Most projects today use Swagger based REST apis. Swagger is presented in YAML or JSON format and can also be viewed online. If you want to read offline documents more easily, you can use swagger-Markdown to generate documents in Markdown format.

We all know that if exported as an offline document, the result is similar to the following:

Does it look more comfortable and convenient than online? The key is that you don’t have to start the service to view the document.

summary

Good documentation can make the project go further and enable new members to understand the architecture and design of the system more quickly. For the developers themselves, they can save time by reading the documentation. It is recommended to spend half a day updating the documentation after every three or four functional iterations, which will provide long-term benefits for the team. As a manager or participant in a team, all three documents are worth thinking about and implementing.

Program new horizon

\

The public account “program new vision”, a platform for simultaneous improvement of soft power and hard technology, provides massive information

\