After participating in the conference Sauve un-e dev, écris un doc ! (by Sarah HAÏM-LUBCZANSKI) at AFUP’s forum, I learned about the importance of project documentation. Thanks to this presentation, I acquired skills to write documentation better than ever before.

In this article, I will introduce 3 steps of writing documentation that I suggest keeping in mind, and then I will show you some cases that I used daily.

Steps for writing a documentation :

Writing a documentation can be broken down into 3 principal steps :

1. Structure: First, the edition of our documentation can be divided into 3 parts: What, Why, and How.

What: Introduce what kind of issue it is and what the issue is.

Why: Talk about the need for writing down this documentation, by listing things such as its context and objectives.

How: Explain the details of how the problem has been resolved

2. Explain in detail: in this step, we should complete our documentation according to the structure we created in the previous step.

To show you what I mean, we can create a README.md file or any other kind of documentation support to show the procedure of how to install a project step by step. We can also add some code examples to make it easier to understand.

3. Improve: It’s necessary to improve our documentation along with all the changes that happen during the project’s life.

Different ways to write documentation for an IT project

There’re various ways to write documentation. On this occasion, I will introduce 3 ways that I use regularly as a novice engineer.

1. Write documentation directly into the code

It’s possible to document our code by adding comments. But, pay attention to this! According to the book “Clean Code: A Handbook of Agile Software Craftsmanship” by Robert C. Martin, we shouldn’t add useless comments:

“Good Comments

Some comments are necessary. But keep in mind, the only truly good comment is the comment you found a way not to write.

Informative Comments

It’s useful to provide basic information with a comment.”

This quote teaches us that we should rewrite our code more correctly and make it more understandable, instead of commenting on incomprehensible code. For example, we can name our variables or our functions based on their purpose. Additionally, we can use abstraction or split them into methods with a single responsibility.

However, sometimes certain cases need to be commented on, such as explaining mathematical algorithmic cases, bug cases, legal cases, and so on.

To give you an idea, here is the code in PHP for validating a postal code :

private const FRENCH_POSTAL_CODE_REGEX = '/^(?:0[1–9]|[1–8]d|9[0–8])d{3}$/';

/**
* Valid examples: "33000", "76000" and "04700"
* Invalid examples: "33 000", "a3000", "76abc" and "0a7e1"
*/
preg_match(self::FRENCH_POSTAL_CODE_REGEX, $postalCode);

In this example, I use the constant “FRENCH_POSTAL_CODE_REGEX” for a given regular expression pattern, but its purpose may not be immediately obvious from its content. Therefore, it’s meaningful to add a comment with some valid and invalid cases of this regular expression.

As human beings, sometimes we forget the reasons why we added certain codes as time goes by. A comment can be useful to remind us of that.

In this case, there’re also different kinds of comments that we can use. For example:

• “@TODO” is used to remind us that there is still something that needed to be added or improved.
• “@deprecated” is used to remind us that we should not use certain methods or classes because they will be abandoned soon.

2. To write a related documentation during the code review

As developers, we use the Git system almost every day, however, we may be unaware of the importance of writing good code reviews on our MRs(Merge Requests) or PRs(Pull Requests).

To begin with, the title is the core of an MR/PR, and a good title helps us understand the proposed changes directly and quickly.

So, the question is, how can we format a good title for it?

First of all, I recommend the notion of Conventional Commit to all of you. This notion guides us on how to format our commit messages, and the rules mentioned there provide us with some ideas on how to format the title of our code reviews.

Besides, we should find out what kind of MR/PR it is and what its context is. For instance, the keyword “feat” is related to a new feature, and “fix” is for patching a bug. Then, we can add a scope to the title to show more details.

Here’re 2 examples:

• “feat(api)” : with the scope “api”, we know that it is related to a feature of an Api.
• “chore(dependency) ”: scope “dependency” shows us that it is for a change of version for a dependency.

After defining the type of MR, we should continue with the second part of the title to describe its details. It should be understandable for everyone even if they aren’t developers.

Let’s suppose that we have a feature to sort companies by their priority. Here we have 3 options, what do you think, which one is more evident?

• option 1 : feat(entity): add $sortBy to entity Company
• option 2 : feat(entity): add property $sortBy to sort companies by ascending order.
• option 3: feat(search): allow to sort companies by label in ascending order

From my point of view, option n°1 is quite technical, we know that it is a feature for adding a new property “$sortBy” into the Company entity. It’s clear for developers but not easy enough to understand for people who do not work in IT.

Based on Option 2, it is apparent that the new property “$sortBy” is for sorting companies. However, it’s important to note that some individuals may not be familiar with the term “property”, which makes the feature less accessible to them.

On the contrary, option n°3 shows us that the new feature is created to sort companies by ascending order without using any technical words. This title is so clear that almost everyone can understand the objective of this feature.

Regarding the content of an MR/PR, we can introduce the context in its description and we can also add some screenshots to show the changes we made.

Sometimes we may forget some formatting rules, which are decided by our team, during our code review, and we may see some errors due to this. Don’t worry! There’s a tool called Danger JS which is used in a CI job and we can configure it in different ways for our needs. It will send us a warning message automatically once an MR doesn’t respect a rule so that we can prevent those issues.

Here is an example of a Danger JS job in my project in the CI “prepare” stage:

Another example of a warning message sent by the Danger JS job is when it alerts us to an error in the naming of the title, and suggests that we should rename it to adhere to the naming convention.

Comments made during code review serve as a form of documentation, which conserves exchanges amongst the team of developers. To effectively format comments and feedback, we can use conventional comments standards.

Firstly, we can introduce the type of comment with a single label, such as “question” to request a clarification or confirmation from the owner for a particular issue, or “suggestion” for proposing some improvements to the current code.

Additionally, we can include a decoration next to the label to provide additional organization to the comment. For example, “suggestion(non-blocking)” could be used to propose a non-essential improvement that does not hinder the approval of an MR/PR.

3. Writing a documentation after having resolved a bug

At this point, you may be wondering why it’s necessary to write documentation about how to resolve a bug.

In my opinion, this type of documentation can serve as a reference for project members who are not aware of the existence of the bug. Providing context and important information can help them understand why the bug occurred and how it was fixed.

Additionally, documenting how a bug was fixed can be a useful resource for other developers who may face the same problem or even those who encounter similar issues in the future. By documenting the steps which are taken to resolve the bug, we can help others to fix the same issue more quickly.

Now, after understanding the importance of documenting bug fixes, the next question will be: “How to write this kind of documentation?”.

During the conference, the speaker talked about the notion of “Developer Loop”, modeled by Kelsey Hightower for the case when developers face bugs.

According to this concept, the documentation can be split into 4 steps:

1. Understand why and how the problem shows up
2. Try to search for an existing solution
3. Prove to ourselves or our team how the solution works
4. Publish the solution

Conclusion

Documentation serves as a powerful means of communication with both present and future audiences, including yourself! So it’s necessary to spend time doing it well. And don’t forget to improve the documentation if needed!

There’re other types of documentation of a project that I haven’t mentioned in this article:

• ADR(Architecture Decision Record) : a type of documentation to introduce and explain an architectural decision of a project. This documentation includes the context, different possible solutions to the problem, the final decision the team has chosen, and its related consequences.
• README.md file : a documentation that provides a tutorial for users on how to install or use a project.
• Wiki : a kind of documentation for internal communication within a team. For example, we can write a wiki documentation to explain some technical features of different roles of a project.

Thanks for taking the time to read through this article. Hopefully it provided you with some valuable insights ! If you are interested, feel free to explore ekino’s website to learn more about our work.

Importance of a documentation was originally published in ekino-france on Medium, where people are continuing the conversation by highlighting and responding to this story.