Shulou(Shulou.com)06/02 Report--

This article was first posted on the official account of Wechat, vivo Internet technology.

Link: https://mp.weixin.qq.com/s/VWjB83NBTg6FwPBDg8G0HQ

Author: Shi Zhengxing

This paper summarizes the experience of a large number of daily consultations encountered in my work and explains what should be written in a development framework document. The logic of document writing is explained from three dimensions: functional framework, feature usage process and functional description. I hope it can give some inspiration to those who are also engaged in the development and maintenance of the development framework.

I. Preface

There was a relatively short period of time when he took over the daily maintenance of more than 10 development frameworks, most of which were still active development iterations. On average, there may be one day a week when you are constantly interrupted by internal instant messaging software to get into a given task, and once you encounter three or two very tricky support or problems that are very time-consuming to troubleshoot, the output will be lower that week.

Some people will say, can't you focus on answering users' inquiries? The answer is that it is best not to, because we put user satisfaction in a very important position, and the timeliness of the response undoubtedly has an important impact on user satisfaction.

After summarizing and classifying the problems:

(1) the first type of daily support, which accounts for about 40%, is about how to use this development framework in a particular scenario (because the document structure is chaotic when the user takes over maintenance, it is difficult to find the desired content in the document quickly. Or there is no such content at all, users can only inquire by phone or face-to-face)

(2) the second category accounts for about 30% of the unexpected conditions in the course of use, which need help to locate and troubleshoot the problem.

After thinking and summing up many times, I think there is a lot of room for optimization. After optimizing the document according to my idea, it is estimated that it will save me nearly 1 day a week. Next, I will introduce my ideas and practical experience.

Second, the definition of the problem and my thinking. 1. Problem description

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

(figure 1)

As can be seen from the figure, ideally, developers only need to send information to users through documentation, and in fact, many open source frameworks are also used, although users still have channels to communicate with developers (such as email or github issue), but that is low frequency. In reality, the basic development framework within large companies not only needs to write documents, but also needs to communicate with internal users in many kinds and channels.

In order to give you a general understanding of what kind of communication this is and the documentation problems I face, here I will slightly modify the real cases in the past-- with a view to abstracting more problems from fewer cases-- as follows.

1.1. Case 1

An old employee wanted to use the circuit breaker framework to protect his system. Through the link to our team's wiki home page saved by himself, he found the link to the document of the circuit breaker framework. After carefully reading all the documents for 15 minutes, he was not sure why he should use the circuit breaker framework provided by our team instead of directly using open source. He didn't think much about it. He wrote a demo according to the document description and finally ran.

Then prepare to be formally applied to the business code, he learned from the document that he may need to adjust some initialization parameters according to his business situation, but because the parameter description is very simple, he has never used the circuit breaker framework before. coupled with the strong professionalism of domain knowledge, seeing that he basically did not understand what the specific results could be achieved, he was ready to call for advice. So he saw that the creator of the document was not the same person as the most recent modifier, hesitated for a moment, and called the recent modifier.

1.2. Case 2

A classmate with many years of experience in java development in Nanjing took over a development task with a large amount of data. Since I participated in the training and sharing of spirng boot-based scaffolding (hereinafter referred to as scaffolding) within vivo, found our project website from ppt, downloaded the project, tentatively searched from wiki, and found our document "using scaffolding to quickly integrate vivo-mybatis". After reading the document, he was still not sure whether his sub-database and sub-table single-database multi-table scenario was supported, so he called to inquire. After consulting to confirm the support and understand the configuration differences between single-database multi-table and multi-database multi-table, he added the plug-in of sub-database and sub-table in the configuration file of mybatis, but the document did not introduce the principle of sub-database and sub-table, and there was no single-database multi-table configuration example, which did not work several times. finally, he decompiled and looked at the source code of the framework and made it clear that the configuration mode was solved, but it took a lot of effort.

1.3, case 3

A colleague searched wiki for two documents about the access of the spring boot project to the vivo configuration center, which were edited and maintained by different people, and did not know which document should prevail, so one of them called and reported the situation. The writers of the latter two documents verify that the situation is true and need to be merged, but it is difficult to decide whether the merged documents should be placed in the configuration center user documentation directory or in the scaffolding user documentation directory.

2. Problem summary 2.1, case-problem identification

Question1: the document entry needs to be passed by word of mouth; if the link information is not saved, ask from other colleagues.

Problem 2: there are gaps in the content of the document, users can read all the documents in a short time, and do not classify according to the functional features, need to see all the documents.

Question 3: there is no competitive analysis, and there is no clear description of the difference between the internal framework and the same kind of open source framework.

Question 4: the description of the framework configuration parameters is too simple, there is no corresponding domain knowledge introduction, users do not understand or do not understand.

Question 5: the maintained open source-based infrastructure is not customized and optimized according to the company's development environment, and the parameters need to be adjusted before it can be used online.

Question 6: the current owner of the framework is not clear from the user's point of view.

2.2. Case 2 problem identification

Question 1: the address of the project website should be memorized alone, so it is very difficult to publicize it.

Question 2: framework documents are not easily accessible, which requires users to try uncertain search.

Question 3: the user needs to call to ask whether his scenario is supported, indicating that the document does not accurately describe which scenarios are supported, there are omissions, and the demo examples under the relevant scenarios are not given.

Question 4: when the framework is packaged, there is no source code package.

Question 5: the document lacks an introduction to the principle of implementation.

2.3. Case identification of three problems

Question 1: multiple documents say one thing, indicating that there is confusion in the document.

Question 2: it is difficult to agree on which module the document belongs to, indicating that it is not assigned to the responsibility from the user's point of view.

What should be written in the framework document? 1. Layman says product

So far in this article, the problems described about documentation and the scenarios in which they appear have emerged clearly. But before we write a document, we have to have a criterion. What kind of document is a good document? I think the answer is very simple, that is, as long as it can reduce the communication between users and developers, as long as it can improve the efficiency of communication, infinitely close to the ideal state shown in figure 1, then the user documentation of this framework is a good document. So you see, the document is also used to solve a problem, it can be regarded as a stand-alone product. What should be written in the document, that is, what function the product should have.

Next, we analyze the key features of this product:

Core users: framework users; rigid requirements: document-based help, fast and smooth use of the framework; typical scenarios: through reading framework documents, complete daily development processes such as access, use, tuning, problem troubleshooting and so on Product concept: avoid or reduce frequent direct communication between framework users and developers, and even if not, improve communication efficiency, let users use more smoothly, and liberate developers from a large number of daily support; competitive research: can investigate dubbo, spring user documents 2, what documents should be included

Based on my past experience and combined with the analysis of the key features of the above products, I think the complete framework document should contain the following categories.

Background and domain-related knowledge (introducing background, basic principles, domain-related knowledge, proper nouns, raising the knowledge level of some users to the same level of developers as far as possible) applicable scenarios And the corresponding dependence and restriction of access, use, tuning-related quality information (functional testing, performance testing, security-related) user habits (suggestions, knowledge sharing, matters needing attention) architecture design and source code reading guidelines

Because the importance of each part of the document of different frameworks will be different, the description length, presentation mode and content carrier of the above categories will be very different. The following figure is the document directory of the distributed lock framework developed by our team based on wiki presentation. The previous serial number is to facilitate document-based communication with the user (direct communication with the user is inevitable).

(figure 2)

3. Refine the landing

After reading the example figure above, I will be a little more straightforward. Next, I will refine the above six more abstract categories into specific functional pages of wiki, of course, this is only an example:

(1) the home page of the framework: give a general description of the current framework, such as promotional slogans, functional features, what problems can be solved, and usage scenarios; next step guidance, community guidance; if it is based on the open source version, you can also introduce what has been done on the basis of the open source version; if not, it is best to compare with similar open source products (competitive analysis) There can also be core indicators to show competitiveness and popularity and enhance user confidence.

(2) Domain knowledge: the goal is to make the user's relevant knowledge level close to you, let the user understand your behavior and practice, and improve the user's recognition or satisfaction.

(3) Quick start: only the quick access and usage description of the simple scenario with minimum dependence, the user can copy the above code and run it directly, and describe how to obtain it. The demo acquisition method of the example should also be given here.

(4) dependencies and restrictions: describe the dependencies of the current framework, including runtime environment dependencies, maven must rely on and select a list of dependencies (for example, dubbo uses zookeeper and nacos as a registry dependency is different), dependent middleware or business systems; restriction information such as cannot use fastjson as a json tool, must use cluster mode redis cluster, and so on.

(5) configuration items: describe in detail the use of each configuration, what role it plays, and matters needing attention. It is best to have some design logic to configure key, which is easy to understand.

(6) detailed instructions: comprehensive user documentation, for all the capabilities of how to use, describe the description, need to explain all the details.

(7) Multi-scenario usage examples: starting from various user scenarios, the configuration / sample codes are given, and the demo that can be run by downloading and importing IDE is also given to facilitate users with different needs to read.

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

(9) upgrade guidance: used to guide users on how to upgrade the version.

(10) Design and principle: contains various types of design documents, principle instructions, source code guidance. Help deep users understand the operation principle, provide some guidance for source code reading; also need to explain what specifications are followed in the design to help users identify the underlying features.

(11) quality information: functional test report, performance test report, vulnerability scanning report, standardized specifications followed.

(12) FAQ: you can summarize the more typical / common user questions on this page to facilitate other colleagues who have similar questions (similar best practices) to reduce communication workload. It should be noted that this is only a temporary public problem guidance address, and in the long run, the questions frequently asked by users need to be optimized at the system design level, or significantly prompted at the detailed instructions.

Fourth, how to write the frame document

The readers of the documents are generally programmers, and the programmers' thinking logic is strong, so the strong logicality of the documents we write is the basic requirement. The following describes the logicality of the documents from three dimensions.

1. Functional framework logic

The overall logic of the document suggests that it should be compiled in a "total-score-total" manner according to the above six categories. First of all, it is necessary to introduce the framework as a whole, which can be put on the front page of the frame, and then specify the categories of documents to be output (documents of corresponding categories can be selectively written according to different frames. Of course, it is not necessary to output all 6 categories of documents) and enumerate the functional features of the framework, which is a "total-score" process. A single category of documentation or a single feature description document can then be described in detail as a separate module. In addition, users should also add menus to those parts that are viewed more frequently, so as to facilitate users to quickly read, find and browse. Let's take a look at the home page of the distributed lock framework document:

(figure 3)

When writing a single category of documents, it is also necessary to split the document in the form of "total-division" many times depending on the complexity of the specific content. After multiple splits, it is generally necessary to re-"total" the process to combine into a complete functional feature.

In the document directory of the distributed lock framework in figure 2, logically speaking, the content of "dependency and restriction" is relatively small, but it is generally a must-see when using a framework, so it is regarded as a separate module here. "Quick start", as the name implies, is to guide users to quickly understand the framework, which is very important. Pay attention to the simplest words, the simplest configuration, the least code, the least dependence, and the smallest space to explain. The goal is to be able to read it in 2 minutes. "configuration Manual" is, of course, a list of all the framework configurations related, including functional, performance adjustment parameters, but also pay attention to the separation of commonly used configurations and less commonly used configurations, in short, a principle, to maintain a comprehensive and complete, but also classified according to the frequency of use. "detailed description" is mainly from the point of view of user access, use, tuning, matters needing attention, etc., to explain the framework in all directions, generally occupying the largest space. The Multi-scene demo sample recommends enumerating all user usage scenarios and providing sample code for the scenario. "versions and upgrades" are actually release and change logs, version compatibility notes, and corresponding user upgrade notes.

The following is the directory of the "detailed description" page of the distributed lock framework developed for our team:

(figure 4)

2. Function flow logic 2.1 function usage

Functional flow logic can be understood as a series of specific steps when a function is used. For example, the typical steps for using a distributed lock framework are as follows:

Rely on the distributed lock framework jar package through maven-> configure the address of zookeeper or redis-> encode (acquire lock)-> encode (release lock)

Will people feel that they understand and do not understand when this process is written like this? Although the overall process is very simple, the document must not just write these contents, otherwise it will bring endless user communication to developers. For example, the document should also include: indicating the minimum version of a function (which version of the package to rely on), how to rely on the spring environment, spring boot environment, and pure java environment, the scope and troubleshooting methods of dependent three-party package conflicts, zookeeper configuration parameters and cluster availability and framework stability instructions, zookeeper connection management instructions, reentrant instructions for lock acquisition and release process, exception handling guidance, best practices, etc. This is still the most basic way to use API. If it is the way annotations are used, there will be more details to explain. As for what details should be written clearly, it can be gradually perfected, and the document needs to be updated iteratively.

In order to make it easy for users to read, it is recommended to explain it one by one in the form of a flow chart. The relevant details should be explained clearly in each step to avoid phone communication and confirmation of the user's use process.

2.2 principle and source code interpretation

When describing the principle of the framework or the source code, it often involves state change description, life cycle description, etc., it is obvious that the use of conventional flow charts is not enough to express clearly, at this time, the state transition diagram, timing diagram, plus the swimming lane flow chart, the effect will be better. Let's take a look at the TCP connection lifecycle state transition diagram:

(figure 5)

3. Function description logic

It is written in the functional process logic that every step in the process should be clearly written in the corresponding details and improved through the continuous updating and iteration of the document. Here, how to describe these details in an organized and complete way, we need to pay attention to the following points:

Complete: enumerate all the possible items, one by one, without omissions; consider all the influence points: for example, changes in one function configuration may affect other functions; and what if the parameter types returned by fallback methods mentioned in the distributed lock framework are not compatible with those returned by normal business methods? Do not let users ask you; conditions are clear: for example, in meeting what conditions will trigger what logic, you can use if/else/while to write pseudo-code; the meaning is clear: WYSIWYG, the use of rigorous words, not ambiguous; narrative background: if a function is not the best implementation, or different from the open source solution, it is best to describe the background to let users understand you. V. Summary

Finally, to realize that everyone's way of thinking and logical habits are different, no matter how much effort it takes to write a document, it is difficult to be perfect without omission or neglect, so a channel for user feedback is also needed. for example, most document systems have comment functions. The following picture shows the maturity of the document after it connects the user and the developer.

(figure 6)

The basic purpose of documentation is to help users to use the framework, but it can not be ignored that the developer of the framework is also an important user of the document, the document is convenient for users, but also for their own convenience.

This article leads to thinking from the problems existing in daily consultation, thinking that the document is also a product, which is used to solve the problems of specific people. Because I don't understand the product, I can't deconstruct the document from the professional point of view of the product. I can only explain what the document should write according to my own experience. the logic of document writing is explained from the functional framework, the process of using features, and the matters needing attention in functional description. Hope to give some inspiration to those who are also engaged in the development and maintenance of the development framework.

As the developer of the framework, the affirmation and likes of users is our best reward. We will pay attention to the quality of coding, but often ignore the importance of the document, the framework is very good, but the document is poorly written, users do not use smoothly, will greatly reduce the value of the framework. It's important to realize this, write great code, and make the document clear and easy to read, so that users will think that the framework is great, and by the way, they will think that the author is good. If you do too many awesome things, your technical influence will naturally come up.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.