Reading the Documentation

Technical Documentation

A very important skill as a developer is reading and interpreting documentation. Documentation accompanies most of the tech you will use in some form, this could be a website, text files included in the source code (like README's) or built into the tech itself (like --help commands on a CLI.)

Using these docs appropriately is a key skill in learning new tech, designing new systems and debugging existing code. There's so many methods, functions and details involved that you can't possibly remember them all and should be referencing the docs as you code.

In other walks of life documentation is something that people often skim over, or never read at all. This is because people can usually intuit how things are supposed to work and will have a decent amount of applicable experience to draw on.

When coding, we don't have years of experience to fall back on, and as such technical docs should be followed much more closely than real world docs as small details are much more important and docs won't solve all the problems for you.

Consider the analogy of a plumber. A person who's been in the trade for 10 years will probably know the names of all the parts, where to order them from and what most of the part numbers are of the top of their head. They'll still look up anything they don't know and wouldn't hesitate to do so.

We should treat technical docs the same way. As you gain experience and use these tools everyday a lot of the more common methods will become easier to recall and you will probably be able to take intuitive guesses at how things work. This will develop over time and for everything else, you should be looking up the required information as you need it.

JavaScript Documentation (Docs)

MDN (opens in a new tab) is an excellent resource and contains everything they will need to become a successful JS dev. They follow a similar format to most technical docs in that they have 2 basic sections (there could be more)

• Guide: An outline of what the tech is for and common use cases
  • This is a great starting point for high level goals
• Reference: The details of how that is done
  • How to do low level tasks, e.g. what parameters a function takes, return values, implementation details etc.

(MDN has several of these as it covers html, css as well as JS and some others.)

When starting a new project using some tech for the first time the guide is a great place to start to gain an overview of how things work. These sections often contain insights into the motivation and underlying principles and it is well worth your time reading them when tackling something new. You can't read everything as it would take way to long so as a general rule read the intro sections to get an overview of what's happening and then you can read the others as they become relevant.

At northcoders we'll be introducing new topics and tech on a daily basis so keep these docs close at hand, they'll be your best friend.

Interpreting documentation

Documentation will contain all the information that you need to use it. An important distinction is that it won't give you a complete solution for your use case of that tech, but how it can be used in general. When referencing it's important to make a distinction between functionality, and examples.

Consider the MDN page for Array.prototype.filter (opens in a new tab)

Here the docs give a description of what the method does as well as some extra sections:

• an example ("Try it")
• Syntax - more examples of the syntax used
• Parameters - a detailed explanation of what parameters it accepts and what each one does
• Return Value - a detailed explanation of what the function returns

MDN also contains some more explicit descriptions with examples of how to do common operations, not all docs will be this kind and the quality will vary. MDN is excellent however.

There's a lot of information in here as well as links to various other topics that may or may not be familiar. As such we can apply the following general method to help us focus on how to get the most out of the docs:

1. Gain a high level understanding of what it does
2. Use the examples to understand the behaviour of how that happens
3. Use the reference to look up any additional info you might need
4. Apply this to your situation

1. High level understanding

We first use the description of the behaviour it gives us to figure out what the method does and how it behaves. For filter it "creates a shallow copy of a portion of a given array." From this we can conclude that it's making a new array.

Exactly what makes up the filtered array are "just the elements from the given array that pass the test."

How we write that test "implemented by the provided function."

This is then elaborated on by "It should return a truthy to keep the element in the resulting array, and a falsy value otherwise." Therefore we should return either a truthy or falsey value, most likely an explicit true/false.

2. Apply that understanding to the example

This is the example from MDN:

const words = ['spray', 'limit', 'elite', 'exuberant', 'destruction', 'present'];
 
const result = words.filter((word) => word.length > 6);
 
console.log(result);

We can test how well we have understood the behaviours above by using some example code to test if it behaves the way we expect. On MDN you can edit the code inline, but you could always make a JS file yourself to test out this functionality.

1. Makes a new array:

We can this understanding by logging the original words array to see that all the words are still there.

const words = ['spray', 'limit', 'elite', 'exuberant', 'destruction', 'present'];
 
const result = words.filter(word => word.length > 6);
 
console.log(result);
console.log(words, '<< all still there')

Here we can see that the contents of result do not affect words.

2. Returning a truthy / falsey value:

The way filter determines which elements to keep is by the return value of the callbackFn. In this example this is the arrow function that we pass to filter word => word.length > 6. In their example this function returns true if there are words with more than 6 characters and if we alter that condition we should get a different set of results.

For example, if we hard code the function to return false, every word should be removed, regardless of it's length.

const words = ['spray', 'limit', 'elite', 'exuberant', 'destruction', 'present'];
 
const result = words.filter(word => false);
 
console.log(result, 'empty array as we returned false for every word');

3. Use the reference for additional details

So far we have gained enough understanding to perform filters based on the elements themselves. There is some additional functionality offered by filter. For example the second argument to the callback function is the index of the element. Depending on your use case this may or may not be useful and once you understand the behaviour you can look up additional options or arguments you may need for your implementation.

An example of when it might be useful:

const words = ['spray', 'limit', 'elite', 'exuberant', 'destruction', 'present'];
 
const result = words.filter((word, index) => index < 3);
 
console.log(result, 'first 3 words in the list');

Apply understanding to your use case

The final step is where a lot of people make mistakes. A key skill here is to separate the functions behaviour from the logic of the example. This is sometimes referred to as business logic, i.e. this is where you'd do some custom code to suit your use case. Once at this stage the method in question is un-opinionated about what it's being used for and it's our jobs as devs to fill this in.

In this case, the filter method itself is not about words, or lengths or even comparisons. These are purely an example to make it easier to understand with a simple example and that example should not be given too much significance. The conclusions we can draw are that filter is used to make a new array, containing a subset of the original elements. Everything after that is implementation detail and we can use JS to filter it in any way we like. We do that by returning truthy or falsey values.

General process

When using docs you should follow this general outline:

1. Gain a high level understanding of what it does
2. Use the examples to understand the behaviour of how that happens
3. Use the reference to look up any additional info you might need
4. Apply this to your situation

Dealing with unexpected behaviours

When making predictions about how you think things are going to work we will never be right 100% of the time.

If something doesn't behave as we expect it to then that is not a bad thing and is not something worthy of concern. What is does mean is that our current understanding is wrong in some capacity and we should adjust it based on the actual behaviour of the code.

This should be viewed as gaining knowledge, rather than being wrong. It's going to happen a lot and is a natural part of the learning process. As such we should embrace it and be actively looking for these situations to enhance our understanding.