Talk about the formulation of technical specifications

Almost all technology companies will pay attention to technical specifications, but the substantive role of these specifications is like "please maintain indoor hygiene, no litter, and no spitting."

The author has worked for 15 years, which is a lot of experience in 15 years, and has also worked in different companies. Almost every company will encounter various specifications. With the development of my career, I have finally become a specification maker, and I have also presided over the formulation of development specifications, operation and maintenance specifications, testing specifications and so on.

I have done a lot of specifications, and there are countless documents, but the technical staff will not read them at all. Through the meeting, the people in the meeting have no intention to pay attention to your specifications. The resistance to the implementation of the specifications is very large and the effect is poor.

Finally one day I realized the existence of the problem and began to reflect on whether companies need to formulate these norms. I found that it has a lot to do with the current environment, and it has a lot to do with corporate culture.

Some mandatory norms can be avoided through some technical means. There is no need for specification if it does not appear! http://netkiller.github.io/

story one

For example, in the following short story, a certain department of the company lost the code that will be developed for several months, so the test could not be carried out.

Regular backup mechanism
Code Comment Requirements
Code access requires higher level approval
Detailed deployment documentation and more

I think there are two main means of source code management, technical means and management means.

Let me talk about management methods first: For example, usually through rules and regulations, accountability and other means, employees are required to meet the normative standards, but usually the execution ability will be discounted, unable to meet expectations, and there are too many unstable factors of people. It is often too late to find that the employee does not operate in accordance with the norms, and the dismissal of the employee cannot restore the company's losses.

Just as the company's rules and regulations are clearly written, employees are required to submit code to the repository, but for various reasons, it is not implemented. When the code is lost, the company will be held accountable from top to bottom, and the company's losses cannot be recovered.

So I advocate technical means: For example, if the source code is released online, it must go through the version library, and only automatic deployment can be used, and programmers are not allowed to hand over the code to operation and maintenance for manual deployment. In addition, the colleague who publishes the code does not need to provide the login permission of the production server, and he can only publish the code through the tool. The deployment process is as follows: Source code (programmer) is submitted to the development branch UAT stage ----> merged into the testing branch Beta stage (supervisor merges, programmers do not have permission) ------> master branch (supervisor merges) -- ---> Automatic deployment system (operation and maintenance) ----> Production server. In this way, the possibility of code loss due to employee resignation, hard disk damage, etc. is prevented by technical means. The code publisher also does not need to check the deployment documents, manually log in to the server and follow the deployment instructions one by one, which prevents personnel misoperation, improves deployment efficiency, and saves labor costs. Usually, all deployments can be completed within 5 minutes. http://netkiller.github.io/

story two

Let me give another example, which is the coding standard in development. Do many software companies have it?

For example, programmers are required to: if (){} to be written as if () { ... }, etc. The requirements are not listed one by one, and even code reviews are organized to solve coding standard problems.

My suggestion why don't you set up auto-formatting on the IDE, or call the formatter via hooks on svn/git commits. http://netkiller.github.io/

story three

The management requires the operation and maintenance to send a server status report every day. The operation and maintenance personnel need to log in to each server or obtain the server running status data from tools such as cacti, and then make a report document and send it to you once a day.

The operation and maintenance needs a full-time person to do this report, and almost no one reads this kind of report, just like the "People's Daily" people never read it.

When the operation and maintenance accident should occur, it still occurs. The boss scolds one by one, deducts wages and bonuses, the operation and maintenance feel aggrieved, and the company suffers losses. These daily tasks cannot avoid operation and maintenance accidents, nor can they improve the operation and maintenance work.

story four

For example, the operation and maintenance work requires data backup. Employee A is responsible for the backup, and employee B is responsible for checking the backup of employee A. As a result, an accident occurs two years later, and the data needs to be restored. There is no work for checking A. At first, the backup was carried out according to the procedure the previous year. Later, A found that B was no longer strictly checking the work, and the backup work gradually decreased. Finally, the backup was stopped, and everything was safe until the incident. http://netkiller.github.io/

story five

I once met a conscientious manager who formulated specifications and required colleagues on duty 7*24 hours to perform operations at regular intervals to verify the normal operation of the system, so that the operation and maintenance can be notified as soon as possible to deal with the failure. Colleagues on duty and occasionally lazy, he got up in the middle of the night to monitor their work. It's really admirable that a worker can do this. But we have a better way that really doesn't have to be so laborious and inefficient.

These stories are an endless loop

There is a problem -> the specification is made on the post -> no one sees/looks and slowly forgets/the stone sinks into the sea -> the problem continues. Consecutive problems occur, administrative measures are used, bonuses are deducted, etc. Many managers attribute this to weak "execution," which I don't think so.

I feel like a lot of norms are formalism. I have always advocated pragmatism.

It is possible to avoid many meaningless specifications through technical means, development automation, test automation, and operation and maintenance automation. This is the trend and the goal of my efforts. http://netkiller.github.io/

The above are just a few examples, which are more one-sided and cannot fully express my thoughts. More communication is needed. Your comments and suggestions are welcome.

http://netkiller.github.io/