In this paper, starting from vivo Internet technology WeChat public links: https://mp.weixin.qq.com/s/VWjB83NBTg6FwPBDg8G0HQ author: Shi Zhengxing

This article takes a look at the many daily consultations I have encountered in my work and explains what a development framework document should look like. The logicality of document writing is explained from three dimensions: function framework, feature using process and function description. Hope it can bring some inspiration to those who are also engaged in the development and maintenance of development framework.

One, foreword

During a relatively short period of time, I took over the daily maintenance of more than 10 development frameworks, most of which were still in the state of active development iterations. On average, there might be one day a week when the internal im software interrupts you so that you can’t get into your assigned tasks, and when there are three or two support or problems that are very difficult and time-consuming to troubleshoot, that week’s output will be low.

Can’t you focus on answering queries? The answer is best not, because customer satisfaction is very important to us, and the timeliness of the response undoubtedly has an important impact on customer satisfaction.

After the summary and classification of the problem:

(1) The first type of daily support, accounting for about 40%, is about how to use the development framework in a particular scenario (because users use the document structure is chaotic when taking over maintenance, it is difficult to quickly find the content they want in the document, or there is no such part of the content, users can only consult by phone or in person);

(2) The second category accounts for about 30% of the expected conditions in the process of use, need help to locate and troubleshoot problems;

After many times of thinking and summarizing, I think there is a lot of room for optimization. After the document is optimized according to my ideas, it is estimated that I can save nearly one day of time every week. Next, I will introduce my ideas and practical experience.

Second, the definition of the problem and my thinking

1. Problem description

Below I show the relationship between documents, framework developers, and framework users in the ideal state (left) and real state (right).



As you can see from the figure, ideally developers only need to communicate information to users via documentation, and in fact many open source frameworks do the same. Although users still have channels to communicate with developers (such as emails or Github issues), they are low-frequency. In reality, a basic development framework within a large company requires not only documentation, but also constant communication with internal users in many different ways.

To give you an idea of what kind of communication this is, and the documentation problems I’m facing, I’m going to present real cases from the past, embellished in a way that abstracts more problems from fewer cases, as follows.

1.1. Case 1

An old employees want to use the fuse frame to protect our systems, through their save our team wiki page link found fusing framework document, spent 15 minutes after careful look at all the documents, I’m not sure why want us to use our team provided by fusing framework, and not directly through open source, he didn’t think much, Wrote a demo directly according to the description of the document, and finally ran;

Then prepare a formal application on business code, he learned from the document may need to adjust some of the initialization parameters according to their business, but because the parameter description is simple, also did not use before fusing framework, combined with professional domain knowledge is strong, look at the basic do not understand the specific can achieve what effect, is ready to call consulting, So he saw that the document had been created by a different person than the one who had recently modified it. Hesitating, he called the person who had recently modified it.

1.2. Case 2

A student with years of Java development experience in Nanjing took over a development task with a large amount of data; As I participated in vivo’s internal training sharing of Scaffolding based on Spirng Boot (hereinafter referred to as scaffolding), I found our project website from PPT, downloaded the project, tried to search from wiki and found our document “Using Scaffolding to quickly integrate Vivo – Mybatis”. After reading the document, he was still not sure whether his single database multi-table scenario supported, so he called to inquire; After consulting confirm support and understand single library table with multiple library table configuration differences, he added the depots in mybatis configuration file table of plug-ins, but there is no this paper introduces the principle of depots table, document and no single library table configuration example, not tried several times, he finally saw after decompiling framework after part of the source code, has been clear about the configuration way, The problems were solved, but with considerable effort.

1.3 case 3

A colleague found two documents about the connection of Spring Boot project to vivo configuration center on wiki, which were edited and maintained by different people. He didn’t know which document should be used, so he called one of them to report the situation. The authors of the latter two documents verify that they are true and need to be merged, but have difficulty deciding whether to place the merged document in the configuration center user documentation directory or the scaffold user documentation directory.

2. Problem summary

2.1 Problem identification of case 1

Problem 1: Document entry requires word of mouth; If you don’t save the link, ask another colleague.

Problem 2: The contents of the documents are missing. Users can read all documents in a short time, and they are not classified according to functions and features, so they need to read all documents.

Problem 3: There is no competitive analysis and no clear introduction of the differences between internal and open source frameworks.

Problem 4: The description of framework configuration parameters is too simple and does not provide relevant domain knowledge, causing users to fail to understand or understand it.

Problem 5: The basic framework maintained based on open source is not customized and optimized according to the company’s development environment, so parameters need to be adjusted before it can be put into use.

Problem 6: The current owner of the framework is not clear from the user’s perspective.

2.2 Problem identification in Case 2

Problem 1: The website address of the project needs to be memorized separately, which is extremely difficult to publicize.

Problem 2: Framework documents are not easily accessible, requiring users to try an indeterminate search.

Problem 3: The user needs to call to ask whether his scenarios are supported. It indicates that this document does not describe exactly which scenarios are supported. There are omissions, and no demo examples for related scenarios are provided.

Problem 4: When the framework is packaged, there is no source package.

Problem 5: There is a lack of documentation on implementation principles.

2.3 Problem identification of case 3

Problem 1: Multiple documents say the same thing, indicating confusion in the documents.

Problem 2: It is difficult to reach an agreement on which module the document belongs to, indicating that responsibility is not assigned from the perspective of users.

What should I write in the framework document

1, laymen say products

So far in this article, the documentation problems described and the context in which they occur have clearly emerged. But before we write a document, we should first have a judgment criterion, what is a good document? I think the answer is simple: as long as the communication between user and developer is reduced, as long as the communication efficiency is increased, and as long as the ideal state as shown in Figure 1 is infinitely closer, then the user documentation of this framework is good documentation. So you see, documentation is a solution to a problem, and it can be viewed as a stand-alone product. What the documentation should say, that is, what the product should do.

Next, we analyze the key features of the product document:

  • Core users: framework users;
  • Rigid requirements: fast and smooth use of the framework with document-based help;
  • Typical scenario: Complete daily development processes such as access, use, tuning, and troubleshooting by reading framework documents.
  • Product concept: Avoid or reduce frequent direct communication between framework users and developers, and at worst, improve communication efficiency, make it easier for users to use, and free developers from a lot of daily support;
  • Competitive product research: research dubbo, Spring user documents

2. What should the document contain

Based on my own experience and the above analysis of the product’s key features, I believe that a complete framework document should contain the following categories.

  1. Background and domain-related knowledge (introduce background, basic principles, domain-related knowledge and proper terms, and try to bring the knowledge level of some users to the same level as developers)
  2. Application scenarios and their dependencies and restrictions
  3. Access, usage, tuning
  4. Quality information (functional testing, performance testing, safety related)
  5. Cultivation of user habits (suggestions, knowledge sharing, matters needing attention)
  6. Architecture design and source code reading guide

Because the importance of each part of the document of different frameworks will vary, the description length, presentation mode and content carrier of the above classification will vary greatly. The following figure is the document catalog of the distributed locking framework developed by our team based on wiki presentation mode. The preceding sequence number is intended to facilitate document-based communication with the user (direct communication with the user is unavoidable).



3, detailed landing

After looking at the above example, it will become a little clearer. Next, I will break down the six abstract categories into specific wiki feature pages. Of course, this is only for example:

(1) Frame home page: an overview of the current frame, such as the slogan, features, what problems can be solved, use scenarios; Next step guidance, community guidance; If you are developing on an open source basis, you can also describe what you are doing on the open source basis here. If not, it is best to compare it to open source similar products (competitive product analysis); There can also be core indicators to demonstrate competitiveness and popularity and improve user confidence.

(2) Domain knowledge: The goal is to make the relevant knowledge level of users close to you, so that users can understand your behavior and practice, and improve user recognition or satisfaction.

(3) Fast start: only the quick access and use description of simple scenarios with minimal dependence, users can copy the above code to run directly, and describe how to obtain it. The way to get a demo of the example should also be given here.

(4) Dependencies and limitations: Describe the dependencies of the current framework, including the operating environment dependencies, the dependency list maven must rely on and select (for example, dubbo uses ZooKeeper differently from NacOS as the registry dependencies), the middleware or business system it depends on; Restriction information such as fastJSON cannot be used as JSON tool, redis cluster mode must be used, etc.

(5) Configuration items: describe in detail the use method of each configuration, what role it plays and matters needing attention. The configuration key had better have certain design logic for easy understanding.

(6) Detailed instructions: comprehensive user documents, for all the capabilities and features of how to use, to describe all the details.

(7) Examples of multiple scenarios: from different scenarios of users, the configuration/example code is given, and the demo that can be run by downloading and importing IDE is provided for users with different needs to read.

(8) Version release record: used to trace and record the release time and changes of the version.

(9) Upgrade guide: Used to guide users on how to upgrade the version.

(10) Design and principle: including various types of design documents, principles, source guide. Help in-depth users to understand the operation principle, to provide a certain guidance for source reading; You also need to explain what specifications were followed at design time to help users identify the underlying features.

(11) Quality information: functional test report, performance test report, vulnerability scan report, standardized specifications followed.

(12) FAQ: Typical/common user questions can be summarized on this page to facilitate other colleagues with similar questions (similar to best practices) and reduce the workload of communication. It should be noted that this is only a temporary public problem guide address. In the long run, users’ frequently asked questions need to be optimized from the system design level, or they need to be highlighted in the detailed usage instructions.

How to write the framework document

The readers of the documents are generally programmers, who have strong logical thinking. Therefore, it is the basic requirement that the documents we write have strong logic. The following three dimensions will describe the logic of the documents.

1. Functional framework logic

The overall logic of the document suggests a “total-points-total” approach based on the six categories above. First introduces the overall framework, this can be in the frame front page, then it is clear the output document category (depending on the framework can be selectively write corresponding categories of documents, is not, of course, be sure to output all the six categories of documents) and to the enumeration of framework features, it is a process of “total – points”. The documentation for a single category or the documentation for a single feature can then be detailed as separate modules. In addition, the part that the user views more frequently should also add a menu to write separately, so as to facilitate the user to read quickly, search and browse. Take a look at the home page of the Distributed lock Framework documentation:



When writing a document of a single category, the complexity of the specific content should be divided multiple times in the form of “total – points”. Multiple breakdowns generally require a process of “summing” again to assemble a complete feature.

In the document catalog of distributed locking frameworks in Figure 2, the “dependencies and restrictions” section, although relatively small in terms of functional framework logic, is generally mandatory when using a framework, so it is treated as a separate module here. “Fast start”, as its name implies, is to guide users to quickly understand the framework, which is very important. Note that it should be explained in the most concise words, the simplest configuration, the least code, the least dependence, and the least length. The goal is to be able to understand within 2 minutes. “Configuration manual” is of course a list of all the framework configuration, including function, performance adjustment parameters, but also pay attention to the commonly used configuration and not commonly used to separate, in short, a principle, to maintain a comprehensive and complete but also according to the frequency of use classification. Details mainly describes the framework from the perspectives of user access, usage, tuning, and precautions. It usually takes the most length. Multi-scenario Demo Example you are advised to enumerate all user scenarios and provide example codes for these scenarios. “Version and Upgrade” is basically release and change logs, version compatibility notes, and upgrade notes for corresponding users.

The following is the directory of pages for the distributed locking framework developed by our team:



2. Functional flow logic

2.1 Function Usage

Functional flow logic can be understood as a series of specific steps in the use of a function. For example, the typical steps for using a distributed locking framework are as follows:

Set the address of ZooKeeper or Redis. Set the address of ZooKeeper or Redis. Set the address of ZooKeeper or Redis.

Does that make sense and make sense to you when you write it this way? While the overall flow is simple, the documentation should not be just about that, or it will lead to endless user communication. For example, the document should also contain: Specify the lowest version of a function (depending on which version of the package is appropriate), how to rely on the Spring environment, Spring Boot environment and pure Java environment, the scope and troubleshooting method of the dependent tripartite package conflict, ZooKeeper configuration parameters and cluster availability and framework stability description, ZooKeeper connection management description, Reentrancy instructions, exception handling instructions, best practices, etc. This is still the most basic way to use an API, but there are more details to explain when using annotations. As for what details should be clear, it can be gradual, and the document needs to be updated iteratively.

To facilitate user reading, you are advised to use a flowchart to explain each scenario one by one. Each step should be clear about the details, avoid the user to use the process of telephone communication confirmation.

2.2 Principle and source code interpretation

When describing the framework principle or source code, it often involves state change description and life cycle description, etc. Obviously, the conventional flow chart is not enough to express clearly. At this time, it will be better to change to state transformation diagram, sequence diagram and flow chart with swimming lanes. Let’s take a look at the TCP connection life cycle state transformation diagram:



3. Function description logic

It is written in the logic of functional process that every step in the process should be clearly written with corresponding details, which should be improved through continuous update and iteration of the document. In order to make these details clear and complete, note the following points:

  • Complete: list all possible items, one by one, do not have omissions;
  • Consider all impact points: for example, a change in the configuration of one function may affect other functions; What if the fallback method return parameter type mentioned in the distributed locking framework is incompatible with the normal business method return parameter type? Don’t let the user ask you;
  • Clear judgment of conditions: for example, if/else/while can be used to write pseudo-code when satisfying the conditions and triggering the logic;
  • Clear meaning: What you see is what you get. Use words carefully to convey meaning without ambiguity.
  • Narrative context: If a feature is not best implemented, or differs from open source solutions, it is best to narrative context so that users understand you.

Five, the summary

Finally, realize that everyone’s way of thinking and logical habits are different, and no matter how much effort you put into writing a document, it is difficult to achieve perfection and omissions. Therefore, you also need a channel for user feedback. For example, most document systems have comments. Below is the document’s mature state as it connects users and developers.



The basic purpose of documentation is to help users to use the framework, but it can not be ignored that the developers of the framework are also important users of the document, the document is convenient for users at the same time, but also to facilitate their own.

In this paper, the problems existing in daily consultation trigger thinking, and the association of the document is also a product, used to solve the problems of a specific group of people. Because I did not understand the product, I could not deconstruct the document from the professional perspective of the product. I could only explain what the document should write according to my own experience. I explained the logic of the document from the functional framework, the process of using features, and the matters needing attention when describing functions. I hope to inspire those who are also engaged in the development and maintenance of development framework.

As a framework developer, the user’s affirmation and praise is our best reward. We pay attention to the quality of the code, but often ignore the importance of the documentation, the framework is great but the documentation is bad, the user does not use it smoothly, the value of the framework is compromised. It’s important to realize that when you write great code and make your documentation clear and easy to read, the user will think the framework is great, and by extension, the author is great. Do a lot of cool stuff, and your technical influence will naturally come up.

For more content, please pay attention to vivo Internet technology wechat public account

Note: To reprint the article, please contact our wechat account: Labs2020.