{"id":1064,"date":"2019-08-01T11:47:52","date_gmt":"2019-08-01T08:47:52","guid":{"rendered":"https:\/\/flatlogic.com\/blog\/?p=1064"},"modified":"2024-03-13T20:13:52","modified_gmt":"2024-03-13T17:13:52","slug":"writing-documentation-for-your-javascript-project","status":"publish","type":"post","link":"https:\/\/flatlogic.com\/blog\/writing-documentation-for-your-javascript-project\/","title":{"rendered":"Writing Documentation for Your JavaScript Project"},"content":{"rendered":"

Nowadays, as a Javascript Web Developer<\/a>, you rarely build anything from scratch: your daily job mostly consists of integrating various Javascript<\/a> libraries. Building a web app typically involves a stack of technologies: React, Vue, or Angular for the front-end, Redux or GraphQL for data management, and Express and potentially Loopback for the backend, with Jest, Mocha, or Jasmine for testing. Additionally, UI frameworks like Bootstrap and charting tools are used, collectively forming the foundation of efficient and scalable business software development<\/a>.<\/p>

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!<\/p>

So how do you learn all of these tools? Of course, there is a such thing as documentation. <\/p>

Why documentation is important?<\/h2>

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 the 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:<\/p>

People will not even consider your project unless it is well-documented<\/h3>

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<\/a>, 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:<\/p>

You will not be able to understand your code in 6 months<\/h3>

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? \"Professional <\/a><\/p>

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. <\/p>

Documentation is a love letter that you write to your future self.<\/em><\/p>– Damian Conway<\/em><\/cite><\/blockquote>

Documentation makes the code better<\/h3>

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.<\/p>

What to write? <\/h2>

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.<\/p>

Define your audience<\/h3>

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.<\/p>

What problem your project solves<\/h3>

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<\/a> (one of our popular admin templates<\/a>) with its documentation<\/a>. <\/p>

\"javascript
Sing App React Admin Template documentation<\/em><\/figcaption><\/figure>

Quick start and installation steps<\/h3>

Most people do not like to wait. So do your users. Let them launch and try your project as fast as you can. Prepare a simple short list of steps needed to setup the project and put it on top of documentation front page. Usually it may be a list of commands required to setup an environment and start the application. If it’s possible, it will be great to simply copy-paste these commands and have the entire application or library launched. Take a look at Rails Admin documentation<\/a> as an example:<\/p>

\"javascript
An example of quick setup steps<\/em><\/figcaption><\/figure>

A list of steps needed to setup the library is clear and easy to execute, which makes the whole project more attractive to use.<\/p>

Hopefully your users will be able to setup and launch everything, so now it is time to go a little bit deeper.<\/p>

Components and features documentation<\/h3>

It is most likely that quick starting the project will not be the only option available to interact with it. There will be other parts, modules, components, features, classes, etc. You name it. E.g. pieces of your software that require separate documentation and provide an API to interact with it in some way.<\/p>

The first thing to do is to list all of these components and make a table of contents based on it with links following to the relevant pages. <\/p>

For every single piece of your documentation it is better to apply the same principle you apply to writing project description: name the component, describe what it is used for, what is the installation process, if there is one. What are the API methods and parameters, if so? Try to put yourself in a place of this imaginary persona you described earlier and imagine what would be the questions and difficulties integrating this particular component. Help them use it and leave no feature undocumented!<\/p>

A list of steps needed to setup the library is clear and easy to execute, which makes the whole project more attractive to use.<\/p>

Hopefully your users will be able to setup and launch everything, so now it is time to go a little bit deeper.<\/p>

\"javascript
Firebase documentation. Table of contents and single component parts are clearly visible<\/em>.<\/figcaption><\/figure>

Firebase documentation<\/a> is a great example of structuring docs. You can see the menu of all available documentation parts on the left side and interact with particular component in the middle of the page.<\/p>

License and contribution instructions<\/h3>

There must be something that guides relations between your project and its users. You have to decide under what conditions your software is distributed and can be used. There are lots of standard licenses available around the web, so it is up to you to pick the right one for your project. The most popular ones are: BSD, MIT, Apache GNU licenses. They are open source, so keep that in mind. Proprietary licenses vary a lot from project to project, so this can be a separate topic.<\/p>

If your project is open source then you are expecting people to contribute. Hence it will be very helpful for them to have some sort of guidance from you. Let them know where they can report issues, ask questions, what are the restrictions or prior assumption before contributing, where they can find issues, etc. Otherwise you are about to lose a great amount of thankful supporters and maintainers.<\/p>

Tips on writing documentation<\/h3>

We will not be able to predict all the use cases and the way users will use your documentation. In general it is a great principle to keep imagining yourself as your user and organize everything based on this point of view. However, here is a short list of general tips every project documentation must follow:<\/p>