My Documentation Reading Process

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

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:

Working through the problem

Getting started

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

$(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. After reading the w3schools article about val() 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:

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 on 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:

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) function, which allows you to pass a value to be assigned to the designated attribute.

I updated line A to be:

$(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? ❓