The Importance of Documentation for Web Developers

The Importance of Documentation for Web Developers

www.hongkiat.com hongkiat.com2 weeks ago in #Web Design Love42

In the development realm of mobile, web, and desktop apps or JavaScript libraries, documentation plays an important role in determining the app’s success. But if you have ever done documentation, you’d agree with me that it is pretty much the least favorite things for developers to do. Unlike writing code (which is what developers signed up to do), documentation has to be easily digested by everyone. Technically, we have to translate a machine language (code) into a language that is understandable to humans, which is tougher than it sounds. Although it can be a real burdensome, writing the documentation is important and will deliver advantages for your users, your colleagues, and especially yourself. Learning Programming: 10 Misconceptions That Are Not True Learning Programming: 10 Misconceptions That Are Not True There are plenty of misconceptions and myths surrounding the art of programming. Many view it as a job… Read more Good Documentation Helps Users Documentation helps the reader understand how a code works, obviously. But many developers make the mistake of assuming that the users of the software will be proficient. Hence, the documentation may be thin material, skipping a lot of the essentials it should have contained from the beginning. If you are savvy in the language, you can figure things out on your own initiative; if you are not, then you are lost. Documentation intended for users usually consists of practical use or the “how-to”. The rule of thumb when creating documentation for general users is that it should be clear-cut. Using human-friendly words is preferable to technical terms or jargon. Real use examples will also be greatly appreciated. A good layout design would also really help users scan through each section of the documentation without eye-strain. A few good examples (aka my favorites) are documentation for Bootstrap and WordPress‘ “First Steps With WordPress”. It helps fellow developers Each developer will have his own coding style. But, when it comes to working in a team, we will often have to share codes with other teammates. So it is essential to have a consensus on a standard to keep everyone on the same page. A properly written documentation would be the reference the team needs But unlike end-user documentation, this documentation typically describes technical procedures like the code-naming convention, showing how particular pages should be constructed, and how the API works along with the code examples. Often we would also have to write the documentation inline with the code (known as the comments) to describe what the code is doing. In addition, in the case where you have new members joining your team later, this documentation could be a time-effective way to train them, so you don’t have to give them a 1-on-1 run down on the code. 10 Programming Habits Developers Should Adopt 10 Programming Habits Developers Should Adopt These outcomes can bring down our confidence but in fact, they can be solved with proper development practices…. Read more It also helps the coder himself The funny thing about coding is that sometimes even the developers themselves do not comprehend the code that they have written. This is particularly true in cases where the codes have been left untouched for months or even years. A sudden need to revisit the codes for one reason or another would leave one wondering what was going on in their minds when they wrote these codes.  » Read More

Like to keep reading?

This article first appeared on hongkiat.com. If you'd like to keep reading, follow the white rabbit.

View Full Article

Leave a Reply