My Documentation Reading Process
Tags: codenewbie, beginners, documentation
Published: 2019-07-09 12:59:52

---
title: My Documentation Reading Process
cover_image: https://thepracticaldev.s3.amazonaws.com/i/m6v032tbn3mconzaifsu.png
published: true
description: After needing to poke through some jQuery documentation, I decided to step through my thought process along the way. 
tags: codeNewbie, beginner, documentation
---

# Intro

Over the past week or two, I've been working through a bit of jQuery with someone, which I had barely used when following an online course last summer and not at all since then. In the process of walking through why their code wasn't working, I realized that technical docs are pretty scary - especially when you aren't very familiar with the language/framework.

Here, I want to walk through my process of reading the technical docs and working through the code to help get the code working! 

## The docs in question

The specific docs I will be referring to here are jQuery's [`attr()` function](https://api.jquery.com/attr/)

## Function Keywords

If you're a bit unclear on the specific words for parts of a function, I don't blame you - there are a lot of parts! If you aren't sure of a word I'm using, need a refresher, or just like sweet infographics, take a quick peak at this tweet from Wes Bos:

{% twitter 1105878111609147394 %}

# Working through the problem
## Getting started

The code that was initially sent to me looked like this (narrowed down to the important parts): 

```javascript
$(document).ready(function () {
  var topic = ["baseball", "hockey", "women's soccer", "basketball"];
  function makeButtons() {
    $("#addButton").empty();
    for (var i = 0; i < topic.length; i++) {
      var buttons = $("<button>");
      $(buttons).addClass("sport")
      $(buttons).attr("data-sport") // A
      $(buttons).text(topic[i]);
      $("#addButton").prepend(buttons)
    }
  }
  makeButtons();

  $("button").on("click", function() {
    var sport = $(this).attr("data-sport") // B
    // ...
  }
}
```

Two lines in particular stood out to me, indicated via my comments of "A" and "B". They stood out because they were using the same function (`attr()`) and argument (`"data-sport"`) but A seemed to be wanting to create the attribute on the button and B seemed to be wanting to read the value from the button. 

## Opening the docs

The first thing I did was search for "Add a value to a button jQuery" and ended up on the docs for the [`val()` function](https://api.jquery.com/val/). After reading the [w3schools article about `val()`](https://www.w3schools.com/jquery/html_val.asp) I realized that this wasn't the function that I wanted. 

A few search results further into the list was the documentation for `attr()`, which indicated to me that it was probably the correct function for _at least_ line A. 

**The reason I didn't start with the `attr()` documentation was twofold:**
1. I wanted to make sure the best function was being used for the task at hand.
2. At this point I wasn't sure which line of code needed to be updated, but I suspected A since it seemed to be wanting to set the value, but wasn't passing a value to store.

## First pass at `attr()`

My first pass at how `attr()` works was not the most fruitful. I jumped to the first block of text (`.attr(attributeName)`) and skimmed through how it works and changed line A to be: 

```javascript
console.log($(buttons).attr("data-sport")) // undefined x4
```

Returning `undefined` was unsurprising, and I started to search for "add an attribute jQuery". These results continued to point me back to `attr()` which made me realize I must be missing something about how the function worked. 

In particular, [this post](https://www.tutorialrepublic.com/faq/how-to-add-attribute-to-an-html-element-in-jquery.php) on [tutorialrepublic.com](https://www.tutorialrepublic.com/) made me realize there was more going on with the `attr()` function than I gathered at first glance.

## Function Overloading
What was occurring within the `attr()` function was something known as "Overloading", which allows a function to act differently based on either the quantity or type of arguments provided.

An example of overloading in Javascript:
```javascript
function add(num1, num2, num3){
  let total
  if (num3){
      total = num1 + num2 + num3
  } else {
      total = num1 + num2
  }
  return total
}

add(1,2)     // 3
add(1,2,3)   // 6
add(1,2,3,4) // 6 -- 👇
/** The function doesn't know what to do with the fourth argument,
    so it ignores it!*/
```

What happens here is that depending on the quantity of numbers passed in, the function will determine if it needs to add the third number to the total based on if there is a third number provided.

## Back to `attr()`

Now that I realized what was happening, I headed back to the docs. Namely, the [`.attr(attributeName,value)`](https://api.jquery.com/attr/#attr-attributeName-value) function, which allows you to pass a value to be assigned to the designated attribute. 

I updated line A to be: 
```javascript
$(buttons).attr("data-sport", topic[i])
```

And... **Voilà!** The inspector was now showing buttons with a `data-sport` attribute!

# Closing
Hopefully walking through how I approached this will help you feel a bit more confident next time you need to use the technical docs to figure out what isn't working quite right. 

❓ _What are your tips for navigating the world of technical docs?_ ❓