The Importance of Documentation - sahajss/knowledge_base GitHub Wiki

###What is Documentation?

According to our beloved source Wikipedia, software documentation is "written text or illustration that accompanies computer software. It either explains how it operates or how to use it, and may mean different things to people in different roles."

An example of documentation:

###The Story

Up until my "aha! moment", I generally didn't read much of the documentation of the libraries I implemented into my project. I would just take a peek at the first page or so just to see what exactly said library could do.

In one point in my lab I needed to create an in-browser text editor that could run code (I picked Python randomly). I implemented a library called CodeMirror, which basically gives you a text editor with formatting (all the fancy colors and key commands that programs like Sublime Text have), and Skulpt (which could run Python and give output).

I first got both libraries working before merging the two together.

#####Skulpt:

Python works yay!

#####CodeMirror

Doesn't CodeMirror look pretty cool?

Both of these worked fine when I worked on them separately. The problem arose when I tried combining the two libraries. Skulpt would not run the code I would change inside the CodeMirror editor.

#####Problems :(

I figured that there was something wrong in the code where Skulpt was getting the code from CodeMirror to run it. After doing some obviously fancy stuff involving the console and changing that to change things. I narrowed it down to this one line of code:

   var input = document.getElementById("inputCode").value; 

It took me way too long to figure out why I was incorrectly trying to get the code from the CodeMirror editor. I finally decided to take a peek at the documentation of CodeMirror. After about 5 seconds of scrolling through the documentation, I found:

Apparently I was supposed to use this to get the code inside the CodeMirror editor, rather than using JavaScript's method, which only got the code from the TextArea that CodeMirror overrode. Oops.

Documentation is important. Reading is hard.