Beyond Code: Understanding the Value of Documentation

Overview

Working as a software engineer in a team necessitates seamless collaboration, where teammates can easily find the information they need. To facilitate this, it is crucial to support your work with comprehensive documentation. This ensures that your teammates can readily access the required information in an effortless manner, fostering clear and efficient cooperation.

Use Case: Flight System

Assuming you are working with a team that is building distributed systems, specifically a microservices application. Let's consider an example of a flight system that consists of three microservices: customer-service, flight-service, and email-service. Additionally, the system includes various components such as databases, caching, and messaging.

Can you imagine? Of course, you can. However, in reality, imagination alone is not sufficient. It is crucial to have tangible resources at hand. That's why it is essential to prepare your first document called the 'High-Level Design' (HLD for short)

What did you feel after looking at the diagram? feeling better, no?

UML Diagrams

As a software engineer, you should be aware of UML digrams , you might be wondering, Isn't self-code doc enough? something like java-doc or maybe swagger! although it is perfectly fine to support your code with these docs, but it is not enough for your teammate to understand your "solution design".

Example

Assuming you have an API that's doing the actual flight booking.

The API is doing the followings:

• validating the input
• calling customer-service to get customer details
• updating the database
• send email via email-service

Now, the question is, How can your teammate know?

Your teammate, who is working with you on the same application, wants to utilize your code, potentially adding new features or integrating it. They need to review your solution design from a helicopter view before diving into the details and without having to contact you.

Here, the Sequence Diagram comes into play.

By providing a supporting diagram for your solution, you can greatly simplify your friend's understanding of the system. This approach ensures clarity for everyone, including new team members. Furthermore, when presenting your work to the team, you will be able to illustrate the solution efficiently, saving valuable time.

Conclusion

Documentation should be mandatory for any system you work on, rather than being optional. Treating documentation with the same level of importance as the code base is crucial. It allows for clear understanding, maintenance, and future development of the system. Moreover, it is essential to choose the appropriate location to store and maintain the documentation, ensuring easy accessibility for the entire team.