It’s easy to get lost specially, in a big project. However, believe it or not, even in small projects or personal passion projects, it’s still easy to get lost because of your own wrongdoing, not documenting properly. As a beginner, or even “experienced,” it’s a hassle having to put comments and document every changes you made to your code, because we always think that our memory will suffice, which is not always the case. If we’re working with a team, many changes are all happening at once, which will make it hard for you to catch up and keep track without proper documentations. Projects that are not often visited can also slip through memory, that’s why trusting memory and thinking codes are self explanatory is setting your self up to failure.

In this article, we’re going to look at a few common reasons why some developers are stubborn when it comes to technical documentation, and later on discuss some of the best practices in documenting for you not to get lost anymore.

So why is documenting a practice often neglected? Let’s look at the following reasons:

1. Laziness

I am as guilty as anyone when I say that I don’t document simply out of laziness, I know I am not the only one. Leaving comments and writing a hefty documentation seems a little more like extra work. We don’t see the benefit of doing it immediately that’s why it is often neglected.

2. Code is “Self-Explanatory”

As beginners, we think that our code is too basic and everyone would understand it. As experienced developers, we assumes everyone is on our level of understanding and we think that anyone would be able to understand the complexity of our code. Truth is, if it’s not our code, or even if it is, it takes time to understand it, that’s where documentation takes place.

3. Relying on Memory

Let’s face it, not all of us have good memory. As developers, we will be involved in multiple projects at once. Even if you have a sole focus, expanding and improving your code will often mess up your memory. It’s important to keep track of stable versions or a checkpoint to help you when times get tough.

4. Lack of Awareness of the Importance of Technical Documentation

Most developers, especially inexperienced ones, just lacks the awareness of the importance of technical documentation and proper communication within teams. Most developers has a lone wolf mentality where they isolate themselves, which often develops the lack of awareness on the importance and benefits of communicating and working with a group.

5. “Make it work first, then Document later” (Proceeds to not write technical documentation at all)

Most developers only documents when their code finally works, which is a sub par practice. I know it is tideous, but it is best practice to also document failed approach, to avoid stumbling upon it once again.

6. Technical Documentation Not taught properly

Lastly, documentation is not taught properly. Watch hours on end of crash courses, tutorials, and formal courses, most often than not, they all focus on the syntax and not the best practices to do when working as an individual or with a group. That is why I think documentation is neglected, because it is not taught properly from the beginning.

That is why I wrote this article, not only do I want to spread awareness of its importance, but I found joy in doing them. Here are some of the ways I document when working on a project:

1. Use of README.md

If you’re the main owner of the project or repository, it is important to write a clear and precise README for your team or anyone who might stumble upon your project. Your README should have the following structure:

• Title
• Description
• Pre-requisites
• Installation Procedure
• Execution Procedure
• Expected Output
• Troubleshooting

There is no standardize way of writing a proper readme document, but following this structure will do. Having all of this elements will ensure a well-rounded documentation of your project. Following this outline, members of your team, as well as visitors of your repository, will have a quick grasp of the project, will know how to make it work, and will be able to handle errors or issues that are common to your project.

 2. Start using of changelog

What is a changelog? It is a document similar to README, but the information that is in here are changes logged in a systematic way. changelog helps your team keep track of the changes made in the project. It can be categorized and sorted in lots of different ways but here is a sample format that you could follow:

• Date or Version
  • Category of Change – Can either be priority like [Minor, Major, Fix, Patch] or Specific Ticket numbers or naming convention of your team
    • Specific Change Made – Summarization of the change that you made

Here is an example:

3. Start commenting on your code

Something pretty underrated I would say is commenting on your code. Most developers assumes that comments are just some extra texts in your code but don’t realize the importance and purpose of them in helping you document your code. Some of the common use of comments are giving descriptions to functions that you created, adding instructions to your code, and mark specific sections of your code for improvements.

4. Start naming your branches properly

Another helpful practice is naming your branches properly. Some acceptable way of naming your branches are the following:

• Specific ticket name or number (if working with a ticketing system)
• Production Environment/Functionality or feature added (prod/popup-modal, test/logout-button, dev/adjust-padding)
• Type of Change/Functionality or feature changed (add/review-page, modified/side-nav)

In this way, members of your team would easily identify the type of changes made in that branch. It also makes it easy to back track stable branches to identify issues or bugs caused by recent changes when debugging. Naming your branches properly not only helps you better communicate with your team, but it also helps you navigate your repository faster.

5. Start writing precise commit messages

Last on the list is writing precise and proper commit messages. For this one, I won’t give anymore elaborate instructions, I will just keep it short. Summarize the changes you made as clear and as concise as possible. It helps your team understand the changes you made when they are merging your branch to another. Lastly, avoid commit messages that are complete gibberish.

As developers, we are taught that we are only focused on making the syntax work, that is why many of us to struggles to adhere to best technical documentation practices. I hope that with this article, you as a developer would start to help yourself improve your communications skill not just your problem solving skill. I couldn’t keep count on how many nights I spent sleepless trying to solve a problem that my own negligence created. At the end of the day, technical documentation is never a “hassle,” it is an investment for the future of your project.

Adhering to the best practices of technical documentation will help you save countless hours of confusion and frustration. By adopting to the best practices, such as writing and maintaining a well-written README.md, tracking changes with changelog, writing meaningful comments, and creating a precise commit message, you’re setting your team up for success. Remember, the work you put in today on documenting, will be beneficial for you and your team in the future.

References:

• technical-documentation