1.Why documentation is important?

2. What to write?

3. Tools to speed up the process

4. Great examples of JavaScript project documentation

5. Summary

Nowadays, as a webdeveloper, you rarely build anything from scratch: your daily job mostly consists of integrating various Javascript libraries together. If you are building a web app you are most likely going to use some framework like React, Vue or Angular for your front-end. To transmit and manage the data you will be using Redux or GraphQL. For the backend, there will be Express and probably Loopback. Then you need to cover everything with tests, so Jest, Mocha or Jasmine must be present too. Finally, there will be UI frameworks like Bootstrap and maybe some charting tools. I have already counted at least 7 core libraries and all of these are in a single project! And what about underlying technologies like Javascript itself, Node.js and, probably, Typescript? Well, that’s a lot!

So how do you learn all of these tools? Of course there is a such thing as a documentation.

Why documentation is important?

There are two ways you can relate to documentation: you can either write or read one. Sometimes you are on both sides, but in most cases you are consuming a creation of other developers. You would not use any of the mentioned libraries, unless they were well documented, would you? Which brings us to the first point:

People will not even consider your project unless it is well-documented

This may seem obvious but, if your code is not documented, then the only way to learn what it does is to reverse engineer it. Would you do that yourself? Let’s consider the extreme opposite and imagine if React, for example, had no documentation. Then there would be only few geeks to try this new tool from Facebook, since it would require browsing over the source code to understand what it does and how to use it. Of course there will be no businesses or enterprises using a non-documented library. What kind of CEO or CTO would want to risk their company’s resources on a technology that has unpredictable onboarding time? Moreover, it would be hard for Facebook’s engineers themselves to support and maintain the codebase, which makes a second point:

You will not be able to understand your code in 6 months

I bet you know the feeling when you look at the code that you have written a few months or years ago and can not understand a single line. It is even hard to admit the code was your creation. Sounds familiar? The code may even look like it was written by someone much less experienced and may seem silly, but still you are unable to explain what is going on there. Why did you write this?

At that moment an intense feeling of regret will creep in and you will start to realize the best moment to write a documentation was when you wrote the code, i.e. 6 months ago. Now, instead of reading the docs, you will have to read the code, and the code does not answer the question “why” it was written and does not explain itself. So the main purpose of documentation is to explain why you wrote this piece of software, including for yourself in the future.

Documentation is a love letter that you write to your future self. – Damian Conway

Documentation makes the code better

You will have to think a lot about the design of your code when documenting it. Since you have to expose the whole structure of the code to the public, you will think twice about the way you built your project. Are there any parts to be refactored? Is there a way to implement some functionalities better or completely reorganize the code? So documentation process itself makes the code better.

What to write?

After it became clear how important documentation is, it seems that we can start creating one. However, before proceeding, I would recommend to stop for a while and do a step zero by clearly defining your target audience and understanding the value your project generates.

Define your audience

This one seems obvious but is often forgotten. It is better to clearly formalize who you are writing for. Who are your users? Are they mostly developers or designers? Experienced or fresh? Do they use your project in a large or small team? Etc, etc. Answering these questions will help you define an imaginary persona, which represents most of your users. Keeping this imaginary persona in mind will help you a lot, so the process of writing docs will look more like a dialog between you two.

What problem your project solves

The first thing to add to your document is a clear definition of what is the name of the project and what problem it solves. It is better to have one or two sentences. People are going to be visiting your page from many sources and, hence, have different perspectives. That’s why you have to be very precise and avoid vague descriptions. Simply state what your Javascript project is about, who it is for and what problem it solves. As an example of proper title and description, you can check out Sing App React Admin Template documentation.

Sing App React Admin Template documentation

Interested in our products? Here is Sing App React admin template itself!