Prefer to write code? Just write it down!

Developers really hate spending time writing things, unless they write code. Yet they also have a plausible aversion to such disgust:

If it's not code, it can't be compiled, and it's not sure it's meaningful.

If it's not code, it can't be executed, so it might never be able to do anything.

If it is not code, it can not be tested, so it can not prove that it is true and correct.

The Agile manifesto does not even emphasize documents: the software that works is better than all the documents.

Is the document useless? I think you know the answer.

Why did you write it down?

A lot of the time, some of the documents in the project will play a big role. But to get those benefits, the developer has to stop the code and take some time to write it down. Let me give you some examples, and I think they'll find the documents worthwhile.

Write down the decision for what to do

If the project lasts for more than a few months, there is always a time when the decision will change the development process. It is possible to decide to use (or explicitly avoid) a particular tool, framework, or platform, either by deciding to write a test in some way or by not writing a test at all, perhaps by deciding to lose the usual practice and doing things in a completely different way. These decisions will emerge and tend to continue.

One day after a long decision, someone on the team (usually the new addition, they're annoying, isn't it?) Would ask, "Why are we doing this?" ”。 What kind of answers will they get?

If a group of people or several people have a good memory and the project is long enough for them, new team members may know the real reason. But most of the time, I'm afraid the answer is "because we always do that." No one wants to hear such an answer.

Keep in mind that if you encounter such an answer, you can have a choice. You can continue to do things the way you always do, because you're numb, or because it's safer to do it, and you don't remember why you started. As a choice, you can make a change and hope you consider all the possible effects. What would be the problem? Oh, and then it turns out there's a lot of problems. For example:

You may be walking a path that has been explored and denied, wasting valuable project time and energy.

Your changes may be in conflict with the way the customer asks for the system to work, and the customer is annoyed.

A moderated compliance review could be disruptive to your way of doing things and cause you and/or your clients to get into legal trouble.

It takes only a little time to write things down and these consequences can be avoided. When your team has made decisions that will change the way you work, write down the date and the logic behind the decision. Later, when someone asks "Why do that" or "Why use that tool," you can answer with confidence.

Preparing for an annoying process automation

Developers often find that they want to automate some processes. These processes are often repetitive and waste valuable development time. However, I often run into some less frequent manual processes (which may occur several months) that involve a series of steps that must be done in a specific order. If no one is willing to take the effort to write down the process, there is a great chance of executing the error, or omitting some steps in the execution, wasting time or even more. Furthermore, without first writing down these steps, there is no practical way to automate the process.

If you find that there are multiple steps in the task that you are performing, and that the task has a great opportunity to perform again, please write down these steps. When someone has to manually execute the process to save time, maybe one day you finally feel very discouraged, so you automate the process, and today's action is ready for that day.