/ #programming

Why Reading the Documentation is Important

Introduction

There was a time when I glanced over documentation when starting on a new project or feature. I was so hungry to get started writing code, that I would quickly skim read the project's readme file or the front page of the 3rd parties api website. This was a fundamental flaw and I’m thankful I have such observant mentors and leads around me, to spot what I was doing and let me know the importance of reading the documentation thoroughly before starting to write any code.

Without fully understanding the code you are about to implement, you are going to run into issues such as incorrectly using a 3rd party API, or implement it in a way that was never intended.

You will find it harder to know what features and functionality are available to you and what settings can be and should be set. Without this knowledge you are likely going to waste time, bashing away at the keyboard hoping to find that functionality or setting you are after, worse still you end up coding extra functionality that already exists.

Why Reading the Documentation is Important

Reading the documentation provided is important, so you understand what it is you are implementing, whether it be an api, client or another application. I use to be a person that quickly scanned the documentation then started to write the code and would figure it out as I went. I ended up implementing the API in a way that wasn’t expected and would miss key implementation details.

Often I don’t need to the read the documentation cover to cover, I will read the main parts that let me know what it does, the key usages and the functionality provided and where I can get further information and help from. I will then thoroughly read the sections that I’m about to implement. This of course is context dependent, meaning it depends what I’m implementing or what I’m trying to understand.

Understanding the documentation gives you a better chance at implementing the right api, client or application. You want to know is it fit for purpose and does it do everything you need it to do. Often people can spend weeks implementing something only to find out that it doesn’t handle the load, or doesn’t do what they actually expected it to do.

I have fallen into the trap of thinking because the api or client is already implemented by someone else, that they must have read the documentation and implemented correctly. An example I can give was when debugging a solution, that used a 3rd party client, the code had been written in such a way that it handled concurrent connections for a single application. When increasing the concurrent connections the application would error. I spent days reading through the code, making changes to try and fix the concurrent connection issue. I finally turned to the documentation and there it was, in the first paragraph stating that this client should not be used for concurrent connections and a single connection per application should be used instead.

What Classes as Documentation

While it’s great to have access to well written online documents, sometimes you are not always that lucky. Sometimes the documentation is not well written, hard to follow or non existent.

That doesn’t give you an excuse not to find out the information you need from somewhere else.

Code

If the api or client you are using is open source. Pull it down and have a good read through, look at what settings they offer, what are the default values set for things like timeouts etc.

Github

Source control solutions often have the ability to add a readme file to the solution. These readmes often contain useful information, that is important to read before hand. Information such as, how to install the application and how the application might be used. Some gotchas and what functions the application contains.

Intranets

A lot of organisations have intranets, such as confluence, these hold lots of information, the one big problem that I have found with intranets is making sure the information is kept up to date. So a word of warning, while it’s a good place to look for information on what application, client, api you are consuming, you need to be weary of how old that information is and make sure other documentation doesn’t exist in other places.

The above ideas are not the only places you can get documentation from, the above are a few examples, there are plenty of other places.

Learning

I find it important to learn the application, client or api and understand how it works before writing a single line of code. I want to really understand what this application is used for and what functionality it has. I want to know what it’s limitations are and it’s strengths. I want to make sure things are working before touching it, such as the tests.

Reading the documentation is now number one on my list when getting started on a new application, client or api. I have found that it’s so important to make sure I have a solid understanding on what it is this code that I’m trying to use, does and to ensure I have spent time learning it first.

Sometimes it might seem like you are using up a lot of time, doing this ‘learning’ when all you really want to do is get in there and code, but for me understanding it well, helps me to write and construct my code better, it also helps me talk about what it is I am implementing and why I have chosen certain ideas and paths.

Summary

It’s important to take your time and read the documentation well before getting started and also when you are stuck. Understanding what it is you are trying to implement goes a long way in making sure that you are implementing it correctly and in the long run will save time, rather than trying to get something to work, in a way that was never intended.

Feel free to comment below with any questions comments.