One of the important parts of the developer's job is to write proper documentation. Learning to write proper documentation is one of the shortcuts to become an amazing developer. The first piece of advice I received from my manager is to document what I am going to build. This is the most valuable advice I have got in my life as a developer. Documentation is one of the most underrated works among many developers, but the main essence of documentation is to think and learn in-depth. In this article, I will be sharing about 3 different types of documentation I came across and how it benefited myself and others.

• Feature Documentation
• API documentation
• Blogging

Feature Documentation

Usually, when we join companies as freshers we are given small bug fixing tasks to get started with the existing system. As young freshers, we will be very much excited to code and push the code to deployment but during code review by senior developers in the team, we may find there are use cases in the system which we have missed. To avoid this discomfort it will be great to start with writing the document.

Before beginning any feature the developer needs to understand the feature they are developing. This in-depth understanding will come from writing the feature documentation; this document will have details like

• What is the feature we are going to build
• What are the various use cases we are targeting
• How it will look like in User Interface
• What is the API we will be using to communicate
• What are the modules we will be working on
• What are the components we will be introducing or using
• What are the new test-cases to be tested

It will take at least 1-2 days to finish this document, the next stage is to share it with other peers or senior developers for review. In 1 or 2 reviews most of the things which we need to build will be clear and mainly we will be knowing the existing resources inside the complex system.

API documentation

Once we finish building our feature the next stage of development is to write the related API documentation.

REST API Documentation

If you are a Backend API developer you should have the practice to write about REST API documentation using OpenAPI Specs (in the future will add a detailed post about this; watch this space). OpenAPI specs make it easy for both machines and users to read the JSON file and understand them. When the API documentation is written using OpenAPI Spec we can use it for generating client library, websites, or for testing.

Source code annotations

Another important documentation inside the source code is writing the comments for every function or method where ever needed. Generally in the complex system most of the time the existing methods are reused again and again. To help other developers in the future who may be reusing the existing method we have to give some sample examples or input values as comments at the top of the method; and if the parameters are passed, we should write a short description about those params.

Blogging

This is a very crucial and final part of documentation by the developer is blogging. It can be internal only blogging or external blogging. For external blogging, we can use pre-built websites like Hashnode (sharing my referral link) or dev.to or WordPress else we can also build some static websites using Github pages. Blogging can be considered as Online Journal on one side, on another side it can be considered as tech notes shared by you to the global community of developers. Many developers may face similar problems, when you share your experience other developers can read and learn from it. Sometimes the steps we followed to solve some problem will be tedious there can be much simpler steps. My wish is every developer should have one technical blog, should write the problems they have faced and the solution they have tried; with this, the internet can become a rich resource for developers.