The Art of Reading Documentation

389 VIEWS

As a developer, one skill that you need to develop is the skill of writing documentation—good and reliable documentation. Not only does good documentation help you, but it also makes it easier for other programmers to collaborate with you on your project. (By good documentation, I mean documentation written with others in mind, not what you write about a variable to explain its function.)

The need to document your code has been stressed by many. I argue that reading documentation is an equally important skill to develop. Documentation is a gift from the developers of a programming language to those who use the language. As such, it is important to both read and understand.  

When I was learning Python a few years ago, I was in a dilemma on where to start. A suggestion I got online was to read the official Python documentation. However, this did not make much sense at the time. I was just beginning, and did not see the need to read something that seemed technical and extremely arcane. A few months down the line, I read it anyway, and I got a deep understanding of the Python language that supplemented what I’d learned from other books.

This is not to say that you have to ditch all other learning resources. Just make an effort to read the documentation, as there is more insight to be gained from reading it.

In my view, there are three main reasons why reading documentation is very important:

You understand the language better

Books about languages and frameworks will never cover all the details. The documentation is usually the only resource that completely covers every aspect of a language: syntax, how-tos, and other essential topics. For instance, at one point I was extremely frustrated when I wrote a thread for a JavaFX app, but did not see any result. However, a quick search of the documentation provided the solution—The thread needed to execute on the JavaFX Application Thread. That information gave me a better understanding of the workings of the language.

Increase your efficiency

In many cases, there are several ways to do one thing in a language. A few factors may determine which way is more efficient. Sometimes, this is clearly spelled out in the documentation. Following the best practices outlined in the documentation prevents you from writing bad code.

Handling errors

Errors are a source of pain for programmers. They are even more difficult to catch if they are “silent” errors. Documentation provides info on how to deal with possible errors that may arise in a program. In addition, documentation gives tips on how to avoid getting these errors in the first place.  

I keep a copy of the documentation of most of the languages I use so I can easily refer to them. A tool that helps me host many of these offline is Zeal. Zeal provides documentation to about 195 developer tools. It also provides IDE plugins for Atom, Brackets, Emacs, Vim, IntelliJ IDEA, and Sublime Text. The search feature in the app makes it possible to search for keywords, classes, and other things in the documentation.  

Zeal supports Windows, Linux, and BSD. It can be downloaded from here. For Mac users, you will find the same functionality in Dash. It can be integrated into Xcode, Android Studio, TextMate, Terminal, and many other IDEs.

Conclusion

Reading documentation is a skill that is going to make your life easier as a developer. It is going to help you as much as writing documentation. Zeal (or Dash in the case of Mac) may come in handy in hosting documentation for some of your commonly used languages. Give it a try.

Do you think you can beat this Sweet post?

If so, you may have what it takes to become a Sweetcode contributor... Learn More.

Bruno is a junior at Ashesi University College studying Computer Science. He is interested in leveraging the power of technology to increase productivity. As a big fan of open source technology, he is currently exploring the possibility of using the Bitcoin Blockchain to fight corruption in government.


Discussion

Click on a tab to select how you'd like to leave your comment

Leave a Comment

Your email address will not be published. Required fields are marked *

Menu