Learning Proper Documentation

Earlier this week I finally finished my JavaScript Node.js package. I finished all the coding and testing, and thought to myself "Okay great job, on to the next project." However there was one thing left to do: documentation. I know the value of good documentation because I've worked with a few large projects in the past. After coming back to a project after a month or two without any documentation, the code can seem very alien to you, as if it wasn't even you that wrote it. I typically try commenting most of my code, however my set-up instructions, project descriptions, and generally my ReadMe file has never been up to par. This project has taught me how to write a cleaner, better looking read me.

GitHub has detailed instructions for creating good documentation that I've been following. It specifies the order and content that a ReadMe generally follows: project name, description, table of contents, installation, usage, contributing, credits, and license. The ReadMe should only contain the necessary information for developers to get started using and contributing to the project, longer documentation can go to the wiki.

There is also plenty of markdown available to make the ReadMe nice and pretty. Markdown ranges from headers and tables, to inline code and even emojis. All the markdown syntax is relatively easy to remember, for example any header is preceded by a number sign (#), with each consecutive number sign representing another header (# is h1 while ###### is h6). My personal favorite is inline code, and it's very simple to use, simply surround your code with ` to inline your code

My ReadMe has went from looking like this..

to this.

Finishing my own node package was pretty. Having a very nice looking ReadMe is just the cherry on top. Having good documentation is not only important for myself to remember my own code, but also to attract other developers to start contributing. These are the valuable skills that I hope to get away from this project.


Popular posts from this blog

Building Mozilla web browser from source

First bugs completed

Async image load test with gh-pages