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.

Comments

Post a Comment

Popular posts from this blog

Building Mozilla web browser from source

-
Image
This week I built the Firefox web browser from source. Mozilla currently has about 17,998,723 line of code, it is mostly built with C++ but also includes other languages such as HTML, C, JavaScript, Rust, and many more. I personally use Mozilla as my preferred browser, so it was interesting to download and modify the source code. Mozilla has easy to read  instructions  that I followed for downloading the source code, building it, then running. I'm using Mozilla on a Windows 10 system. Some of the prerequisites include installing Visual Studio with certain workloads, Rust, MAPI Header Files, and MozillaBuild. Once I installed everything necessary, I was ready to pull the Firefox source code using the command hg clone https://hg.mozilla.org/mozilla-central And then the wait begins. After patiently waiting for the a while, the downloading aborts. Uh oh, what happened? The message read: "Rust compiler not found". I have installed the Rust compiler and have
Read more

Async image load test with gh-pages

-
Image
I finally got the opportunity to try out GitHub Pages. GitHub Pages is a simple static HTML page that we can create from our GitHub repositories. It is perfect for documentation or anything related to the project. To get started, a gh-pages branch must first be created, and then it can be further setup in the settings section. For this project, I wrote a test case for async image loading. I built a simple page that would allow me to test this in multiple browsers. The page is very simple with an image, a counter, and a button to reload the image. As the user clicks the button, the image is reloaded. If the image is reloaded, the background changes colours and the counter is updated. The async testing has passed on all the browsers except for Safari. I decided to dig deeper into this and Safari is like this. I had to dig pretty deep into the webkit source files to see where the load event is fired. After digging around for a little bit, I found the ImageLoader.cpp file. The na
Read more

First bugs completed

-
Image
After working on my bugs for the past few weeks, I've finally completed two of my bugs! The bugs themselves were very simple to solve, but in this process, I've learned how to use a variety of different Git command, including clone, pull, add, fork, and pull request. I use to feel lost while using Git, now I'm much more confident with my new skills. Neither of my bugs were software-breaking bugs, and most users wouldn't even notice them. I finished my first bug in my previous blog, you can go and view it here . Deep inside of Firefox's Dev-tools, one button's boundaries extended to the end of the screen, instead of around the image only. The fix was relatively easy, a CSS class was already created and I only had to place the class name in the correct spot on the HTML page. I left the last blog after I completed the bug, without creating a Pull Request. During my previous lab, I practiced creating a Pull Request, so I had an idea on how to do it this time. I cr
Read more