How to Interpret and Use Documentation as a Student Software Engineer
Tags: beginners, webdev, programming, ruby
Published: 2022-03-30 01:12:49

Since my last blog, I’ve entered into phase 3 of my bootcamp where we’re tasked with learning an entirely new programming language (Ruby) among many other backend-centric concepts. Just like that, despite barely taking the training wheels off with Javascript, it was already time to learn and implement another language. Luckily, after hundreds of repetitions in building apps and solving problems with one programming language, the process is significantly less daunting to learn another.

10,000 foot view: These languages all need to accomplish similar tasks. You need to be able to define variables. You need to be able to write functions. You need to be able to access and modify data in objects and arrays. In my experience thus far, the real differences come down to syntax and built-in methods. The bridge between your more familiar language’s syntax and built-in methods and the language you’re trying to learn is documentation! However, understanding documentation with the purpose of rapidly applying is a skill in and of itself, and one that will be the focus of this blog.

In my previous career, I was a Prosthetist/Orthotist. To make that uncommon job description succinct, I used evidence-based practice to restore mobility to people with limb loss and/or a wide swath of neurological and musculoskeletal conditions. One of the toughest and most important aspects of the job was implementing best practice garnered from reading scientific articles/current research (e.g. evidence-based practice). Scientific articles are very dense and overwhelming to digest until one has read many over time, and most importantly, learned how to effectively parse through them to be able to evaluate the quality of the document and implement the findings. 

As I was learning the basics of javascript (and now Ruby), I noticed a lot of similarities between developer documentation (known colloquially and lovingly as “docs”) and scientific articles, and even experienced a similar amount of dread upon first glance! The initial time I had googled “MDN map” to learn how to use that built-in method in a specific case, I left the page more confused than when I arrived. This is unsurprising given that software engineering concepts, like concepts within science, have building blocks that can’t be skipped if full understanding is the goal. That said, even if a grasp on the building blocks is solid, that doesn’t mean that parsing through docs as a beginner can’t be extremely time consuming.

The parallels between understanding docs and scientific articles (for me), come down to the following two general principles:

- Reading the article (or doc) in-full is rarely required. Focus on what you need! For someone practicing evidence-based rehabilitation, it came down to fully comprehending the methods and results sections. The introduction and conclusion are more important to those in academia. Similarly, to borrow from the map example above, it’s doubtful that the ES2015 implementation of your desired built-in method will be relevant to you at the start of your programming journey.

- If you don’t understand a concept, don’t panic- Google! It was rare that I would come across a novel scientific article and fully understand, for example, a machine they were using for testing and/or an advanced statistical method. A (relatively) quick search would fill in those “building blocks” and allow me to move on in comprehending the article. In the case of software engineering, I had no clue what a callback function was the first time I came across the reference in an MDN doc. Isn’t having unlimited information at your convenient disposal great?


Following these general principles, I’ve been able to greatly expedite my process of learning Ruby. More specifically, I like to quickly hone in on the following four items when parsing through docs:

- What data type the method takes in 
- The needed parameters
- The return value
- An example of implementation

Quickly locating the above will allow me to answer the following questions in a rapid fashion:

- Do my intake, parameters, and return values match?

But what about the locating the example? Were we doing that just for fun? Not quite- the example allows me to have a template to quickly match syntax!

If the answer is “no” to the first three questions, then chances are you will have to find another built-in method (or no built-in method) to accomplish your goal. But knowing what you can’t do is half the battle! For the rest, chances are Stack Overflow or GitHub will have what you need.

Consider the following example in Active Record. You need to query in a pry session by the first name (a string) of a user within a database. You find find (pun intended). Will this specific finder method work for your purposes, and using the above questions, how quickly can you determine if it will or won’t?


![Official documentation of the find findermethod in Active Record](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/47spgwa4b79yolvjt017.png)<figcaption align ="center">https://api.rubyonrails.org/v7.0.2.3/classes/ActiveRecord/FinderMethods.html#method-i-find</figcaption>

One final note, learning to correct syntax and incorrect data type errors through error messages in the terminal has become increasingly valuable to (recently) indispensable for me. I suspect this is the case for everyone as they move through their software engineering journey. Remember that errors are every bit as valuable as expected output! When it stops feeling that way, there’s always docs!