Writing Documentation For Your JavaScript Project - Flatlogic

August 19, 2019 0 Comments

Writing Documentation For Your JavaScript Project - Flatlogic

 

 

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 as an example:

An example of quick setup steps

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

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

Components and features documentation

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.

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.

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!

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

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

Firebase documentation. Table of contents and single component parts are clearly visible.

Firebase documentation 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.

License and contribution instructions

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.

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.

Tips on writing documentation

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:

  • People will simply copy and paste your code. Keep this in mind and make sure to double check this yourself by executing it. Avoid placing some invisible characters to code examples. It is even better to use code and blockquote tags to embed code blocks.
  • Keep your documentation updated. Every change in code must be followed by a relevant change in documentation. Otherwise documentation soon becomes outdated, which is equal to the absence of documentation.
  • Code comments are a part of documentation. This is the last and very important one. If your project is open source, users are going to be reading through your code, hence inline comments will help them a lot. Furthermore, there are tools like JSDoc that generate documentation based on code comments! So you do not have to write anything in a separate file. Simply feed this tool with your codebase and, voila, you have the documentation.

Tools to speed up the process

Why would you want to write and create everything from scratch and by yourself if there are so many documentation tools available? Nowadays generating documentation, especially if you produce high-quality code with inline comments, is a matter of running a single command.

So let’s overview documentation tools available in 2019.

JSDoc

JSDoc is the most popular Javascript documentation generator. All you need to do is to simply run jsdoc command with a filename as an argument. That is it. It will generate HTML file with documentation that is ready to use. The website is https://github.com/jsdoc/jsdoc.

Docusaurus

Docusaurus is a more complex tool that allows you to generate entire documentation website based on markdown files with documentation contents. It is based on React and supports versioning, so you can easily maintain different versions of the documentation generated in the past. Other great benefits are embedded search and multi language support, which is crucial for popular repositories. The website is https://docusaurus.io/.

apiDoc

apiDoc creates a documentation from API annotations in your source code. It is a great tool to generate a documentation for a project that has and exposes lots of API methods. It allows to customize everything a lot, e.g. specify parameters, error codes, response samples, etc. The website is http://apidocjs.com/

Great examples of JavaScript project documentation

When creating something new it is good to have some sort of example, something you can refer to. So here is the list of various projects you may get your inspiration from. All of them are great, so pick one you like the most.

Summary

I hope that you have found this article useful and it will help you a lot when creating documentation for your JavaScript project. Googling the Internet tells that documentation is a key to success in any Javascript project, and I strongly agree with this rule. Documentation is sort of a facade that people face and resort to when using your project. So always keep it updated and put yourself in place of your users!

Originally published at flatlogic.com

Flatlogic creates top Vue, Angular and React admin templates with stunning design and one of the best React Native mobile template.


Tag cloud