How to write good documents

In this article, we explain the reason for forgetting how the project works in three steps. Everything should always be documented in programming teams. Documents must always be next to the code.

This will help you make sure that no one has to guess how things are done and use hypotheses, or have long sessions to learn about a feature. Good documentation saves time and reduces hassle and rework.

Contrary to popular belief, the most valuable software documentation is not written for other people at all. The secret to a good document is to write it while writing code. Before these documents are for someone else, you are your first contact. Explain what you are going to do yourself. You will thank yourself in the future!

Here are three steps you can take to begin the process of preparation for mediation.

1. Start with detailed notes

As you work on the ideas in the code, make sure you don't forget important details by starting detailed notes. While you want to explain everything in more detail later, short notes are enough to get the details.

Keep a document open next to your code and write down things like commands, decisions, and resources used. This may include the following:

Why did you choose one method over another?

Links you have visited for help

Arrange things to be done

Do not worry about complete sentences at this stage. Just make sure you get the right text, code snippets, and useful URLs.

2. Explain decisions more broadly

The ideal time to do this step is when you are not coding and you are resting, but do it before you completely quit your job and go for lunch, for example.

You want to make sure the content, ideas and decisions are all fresh in your mind as you explain them to yourself.

Review your short notes and start spreading them in conversational writing. Describe what you are doing as if you were teaching it to someone else. These may include:

I usually do this, but this time I decided to do something different because ...

Challenges you have faced and how to overcome them

Architectural decisions that support your project goals

Stick to the basics. Long writing does not always mean being good. Use only complete sentences, and write as if you were explaining your project to a colleague. Anyway you are explaining for your future.

3. Do not neglect the required knowledge

This step is best done after a long lunch break, or even the next day. Read your document again and fill in the blanks that will be identified after the distance between you and your project.

Be careful to write or at least link to the required knowledge, especially if you regularly use different languages ​​and tools. Even small things like linking to API documents can save you hours of searching in the future and save you time.

Write or link to READMEs, installation steps, and other related support items. Organize or even automate the command-line actions you take regularly so that you do not have to do the usual tasks every time you return to the project.

You can easily forget the support details even after a short break from your project. So write down everything you find useful.

Document everything

You may think to yourself, this is something I will not forget and I will remember it with a little thought. But most of the time, over time, you will probably forget a lot!

To set the best path to success, record everything, the process you have created, the infrastructure, the features to be added, the order of things, write everything thoroughly and clearly. You will thank yourself for this in the future. These documents will help you a lot first and then those who are going to work with you, and it can be said that it is essential for the better and faster progress of the project.