[clique aqui para português]

I’m a weirdo. I know, that's a strange way to start an essay, but see — I'm the only person I know who always reads the instruction manual.

A while ago, I furnished my apartment and my bedside reading became a pile of manuals for house appliances. I enjoyed the refrigerator manual, but thought the ending was a little cold (…sorry).

Truth is, KitchenAid reader or not, nobody escapes from needing instructions in life and the experience is much more difficult if this document is incomplete or confused.

In software development and tech, documentation has multiple functions:

• Formalize processes and systems
• Learn out loud
• Help people answer their own questions

In all cases, both the writer and consumer benefit from the production of the material. If you want to participate in this knowledge exchange, here's a complete guide on how to write good documentation!

Before you start

Despite the parallel drawn earlier, making software documentation is much more complex than a device manual. That’s because there is no closed set of instructions that can be printed and never revised. Technology is constantly changing, and the most used systems are the most updated. Therefore, the most important documentation is the one that gets outdated faster.

That's nowhere close to encouraging, but it's remediable: most of the time, it's not the entire doc that is obsolete at once. It's the operational, technical details. So, one workaround is to separate the how from the why. How to use the system changes constantly, but why the system exists is a much more stable concept.

That was Etsy's idea when they did an experiment targeting “immutable” documentation. Following this concept to the letter involves other tools and making the process more complex, but we can extract a simple and very applicable lesson (TL; DR): whenever possible, avoid very specific details that can change. For example, instead of saying “We use the Roboto font”, you can give instructions to look for the project’s font in the <head> tag of the index.html file.

First steps

A blank page can be intimidating to the point of paralyzing even the most experienced writer. Here, we have the advantage of being able to start with a defined plan, without having to think too hard. I always follow three steps, in that order:

• Collect reference materials
• List content in macro topics
• Add details and technical part

Before I started writing the Astro Readme (design system at my former employer), I first opened all the references I would use. Then, I listed the information I already knew the document would need to contain. At that moment, I didn’t care much about the order:

Astro Readme

- Instructions for importing the dependency into your project
- How to add the sources
- How to run the project locally
- Where to view online documentation
- How to edit the documentation
- How to deploy the documentation
- Official support for React
- Known errors for troubleshooting

Now that the page is no longer blank, it's much easier to proceed by detailing each of these steps. Before that, however, let’s go into detail about the structure of this document.

Title and introduction

The question you must answer when writing the title and the first paragraph of your doc is: “What is this document for?”

Try to come up with a title that clearly states what the text is about. If that's not enough, the first paragraph serves as a support to understand if this document is where they'll find the information they're looking for.

Mobile Accessibility Guide

This document is a reference guide for recent discoveries and new practices that must be disseminated in our project to continuously improve the accessibility of the mobile app. Right now, our efforts are focused on VoiceOver (iOS) and TalkBack (Android) screen readers.

Steps or items

We can now go back to that information list we mapped in the first step. Now's a good time to try to organize these steps or items in the same order that the reader will need to refer to them. For instance, "Install" and then "Usage".

The best way to present the content may vary depending on the type of process to be described. Step-by-step instructions are clearer if numbered; actions with no defined order can be organized into topics; a less technical issue can be well explained with a FAQ, and so on. When in doubt, test more than one format before defining.

Use very descriptive headings in each of them, to make it possible to quickly find the necessary information. This will also help you create a good index later.

Troubleshooting

In very technical docs, a "Troubleshooting" section can be especially useful for documenting known errors and obstacles and showing the way around them. It's important to keep this section up to date, as it's not uncommon to spend more time trying to fix bugs than actually developing.

Contact

In most cases, it's useful to leave contact info to answer questions and send suggestions by the end of the document. If you're writing a GitHub Readme, the contact section can also point to how and when to open an issue in the repository.

References

Including links to the materials used as a reference at the end of the doc is a good practice both for crediting authors and for readers who may be interested in diving deeper into those subjects.

Keep in mind

While creating this documentation, I suggest that you keep in mind some questions that help you cover as much territory as possible:

• Who will read this documentation — and what's their technical level?

Will this doc be consumed by people within a company team, or by the general public in an open source project? It's necessary to adapt the technical level or detail according to the reader, keeping the text as didactic as possible. Remember that "obvious" is a relative concept; sometimes, we think anyone understands what we consider simple, but this is not always true (I'm looking at you, impostor syndrome).

• Anticipate questions

That's basically an empathy exercise: try to anticipate any doubts that may arise throughout the text and answer them in the same place they appear.

• Single source of truth

The “single source of truth” concept calls for a single location to be maintained as a source of consultation for all matters relating to a subject. It is easier to keep a single place updated, so this is a good practice to aim for.

• Know when to stop

An unnecessarily long document is difficult to read and maintain. Try to discern how far you'll explain a topic within the doc or when it's time to link to a more specialized external tutorial. For more advanced people who may need more details, this is a way to point them in that direction without penalizing others with extra content.

• Stay in scope

Still on the previous item, be as objective as possible. If a tangent process starts to get too detailed, it may be necessary to separate it into another document.

• Link, don’t replicate

Avoiding details that can easily change dramatically decreases the frequency with which the document will be outdated. If the shifting details can be found in a more up-to-date external source (for example, information about a third-party plugin or dependency), it is better to link to it than to replicate that content within your documentation.

Enriching details

So, you covered all the previous points and want to take it a step further? Here are some details that enrich the experience of those who consume your doc.

• 1 reference = 1 link

Whenever you reference a concept or process, e.g. Markdown, find material on that subject and insert a link. Thus, a person who does not know exactly what that is or wants details can learn from a source you selected, which guarantees that you will be on the same page.

• Illustrate

Screenshots, gifs, illustrations, graphics, memes… Choose the best way to illustrate the content and use as many figures as necessary to make the text more dynamic and didactic.

• Information hierarchy

Those in contact with design are already familiar with this concept: the idea is to establish a visual hierarchy to facilitate quick understanding and localization of information. The most useful application here is to explore text formatting to create levels of title and subtitle (such as h1 to h6 headings in HTML), and thus to group macro and micro sets of information. We can also use bold, italics and even colors (like red in points of attention) to add intonation to the text, just as we would in voice speech.

• Practical examples

Whenever possible, add an example of the process described to illustrate its application in practice. This will always make all the difference in message clarity.

All done, now what?

Hold the urge to click “Publish”! Now’s the time to groom and polish your doc. Bear with me, it's just a few more steps:

• Read from beginning to end

When writing, it's normal to go back and forth several times and change paragraphs. Reading from beginning to end helps to review the cohesion of the text flow without interruption.

Time to drop a super important writing tip: the vast majority of people don’t read, they scan. Therefore, it's necessary to test the effectiveness of that information hierarchy, checking if it's possible to jump directly to a topic in the middle of the text and understand what is happening there. That’s what most people will do in your doc, no matter how good it is.

• Edit

When proof reading, in addition to finding improvement points, you should also wipe down, summarize and cut redundant or unnecessary parts. Remember: people don't read everything, so less excess is more clarity.

• Create the index

The index, or “Table of contents” as many call it, facilitates the preview of the content and also allows quick navigation. If the tool allows anchors (links that lead to points on the same page), use them.

• Ask for reviews

Ask people familiar with the documented system to review it, so they can validate that you have covered all points and have not forgotten anything. Then ask unfamiliar people. This is the most important part of simulating how a new person will understand the documentation, and is usually where you'll get the most feedback.

• Always update

After publishing the doc, it’s easy to forget about it forever. Technology documentation is never finished; the best practice is to elect a person or group responsible for maintaining it.

Another great trick for keeping docs updated is asking newcomers to contribute. They will read and use all those instructions for the first time, so that's a great opportunity to spot any outdated or missing info and improve them.

Final reminder

It's important to have well-written and updated documentation, but the software itself is even more important. We don’t want to get lost in detail and forget what our priority is, as the Agile manifesto preaches:

Working software over comprehensive documentation.

This priority is especially valid in the context of a closed company. But, of course, in a public or open source project, this motto has its caveats. After all, without documentation, it's very hard to understand third party code and impossible to contribute.

The final reminder is to always adapt the level of dedication to the documentation according to its context.

That's all for today and see you next time ❤

How to write good documentation was originally published in Lari Maza | En on Medium, where people are continuing the conversation by highlighting and responding to this story.

[clique aqui para português]

DX, or Developer Experience, is a discipline that describes the experience of a developer using a product. In a similar way to UX (User Experience), a good DX makes all the difference in your product’s reach potential, be it an API, a library, a tool or a service. The awareness on this subject has grown so much that there is even specialized work — dev Sarah Drasner’s Twitter bio says “Head of DX @ Netlify”.

In my experience developing Astro, Magnetis’ design system (my former employer), the quality of DX is very relevant to boost user productivity. These people may or may not be Magnetis employees, since Astro is open sourced — which means that the responsibility is even greater.

Based on what I learned there, I bring some attention points to improve the DX of your project:

1. Documentation

It seems somewhat obvious to mention documentation as a main point of attention in DX; but, for an artifact that will often be the only means of communication with the user, it rarely receives the attention it deserves.

In open or closed projects and repositories, some maintainers expect users to understand everything just by reading the code — which is not only bad communication, but also bad empathy. And within teams, the solution to poorly documented projects is often to ask someone, which is also not productive for both sides.

Documenting is your opportunity to explain in human language the purpose and how to use your project. Here, you must teach how to use the design system, but also how to contribute to its code (even if it is not open sourced, newcomers might join the project at any time). Think of these moments separately — you can even create two separate files on GitHub, as we did in the Astro repository with “Readme” (usage guide) and “Contributing” (contribution guide).

I will not go into detail on how to write good documentation because I have already written an article about it, but, in summary, it should include three things:

• Comprehensive: Make sure the document covers any doubts that may arise about how the project works. Explain what it does, how to install, how to use it, and include solutions to known problems. Your goal here is to eliminate the need to contact you directly to answer any questions. Don’t be a bottleneck. The Single Source of Truth must be the documentation, not you.
• Accessible: Don’t assume that everyone who reads the document has the same technical level as you, even if you think you have a low technical level (I’m looking at you, impostor syndrome). Avoid technical terms when possible. Write step-by-step tutorials. Do not assume that the person knows how to clone a project or install dependencies via terminal, for example. Explain to a beginner and you will be explaining to everyone.
• Friendly: Reading documentation can be a tedious activity, so try not to make it unnecessarily long. There is a difference between comprehensive and wordy. Get to the point, use a friendly tone and, if you want to, you can even add a touch of humor.

2. Usage patterns

In the case of Astro, the design system is used by applying CSS classes to a markup structure showcased in the documentation. Here’s an example:

We tried to create class names that are descriptive for humans, instead of something like a-bt--ur__md1, even if they’re longer; we want them to be self-explanatory and memorable, which reduces confusion and the need to consult the documentation repeatedly.

By the way: this is when you realize you’re doing API design. Neat!

Another important point is that class names need to be more specific (like a-btn) rather than completely generic (like btn) to avoid conflicts with existing CSS in legacy projects. The objective is to minimize side effects when importing the design system, and this mindset must be applied to all user-facing (the dev being the user here) points of the project.

Finally, to create a scalable and predictable system, you need to try to maintain a usage pattern that makes sense. This is a big challenge when we receive design demands that are outside the norm, and it may be necessary to negotiate to satisfy these demands while also maintaining consistency.

For example: in Astro, there are many variants of button styles and each one has four colors. A design system tends to scale, and when new colors or styles are introduced, we wanted to follow the pattern and even make it easier to manipulate these buttons with less visits to the documentation.

With that in mind, we created a class structure that varies in a predictable way. a-btn--uranus is the primary button in blue (color we called “uranus”). For the other variants, we added a modifier that can be a-btn--outline-uranus for the outline button or a-btn--ghost-uranus for the ghost button.

Furthermore, the color “uranus” can be replaced with any of the color variants (“mars” for red, “venus” for pink or “earth” for green) in any button and the result is still predictable.

And to define size, the user must add one of the three size classes: a-btn--small, a-btn--medium or a-btn--large. Regardless of which button, the result is always the same.

Here’s a video of me playing around with these modifiers (please open in a new tab):

demo.webm

By creating standards and predictability, usage is more intuitive, error-proof and more independent of documentation.

3. Technologies

Aside from the ground we just covered, good DX criteria still include the consequences of technical decisions, such as difficulty level, package size and barriers to use or contribute.

Please value pure simplicity and avoid unnecessary complexity. Sometimes, we really need new tools to scale the project. But make sure to question if that’s really necessary. For example, if it is possible to write CSS without any frameworks, write it — it is more feasible than it looks. Each layer that we add to the stack can create a barrier for those who don’t have context of that specific technology; we are often not aware of that, because it looks familiar to us. It’s a matter of empathy and inclusion, but also of allowing more people access to your project, by using or contributing.

Try your best not to weigh down your project with dependencies. Each of them requires updates in the future, which can break the project and generate work to adapt it, in addition to being a potential door for vulnerabilities. Don’t lose control.

Keep trying to automate as many manual processes as you can. For example, instead of asking to import typographic fonts or icons manually, include them in the project package and create simple ways to call these assets. Aim for the concept of “zero configuration”.

Test the speed to download and run the project, and look for improvements in this process as well.

4. Update guides

Astro once released version 2.0.0 with breaking changes — that is, with incompatible changes that can cause breaks in the projects where the dependency is installed. In that case, the reason was that some CSS classes and some icon names were changed.

Updating a dependency in these conditions requires careful adjustments to the project in order to avoid unpleasant surprises. What can you do to improve DX?

• Always be mindful of changes that can cause breakage and weigh the benefits before proceeding. Plan the new version to isolate the incompatibility and cause minimal side effects;
• When you release this version (which will be major, according to Semantic Versioning), write an Update Guide mapping all the changes that developers need to make to their projects that use the design system. See Astro’s v2.0.0 Update Guide here as an example.

In conclusion, a design system (or any project) with good DX is a system that’s easy and pleasant to use and contribute. With equal parts of technical quality and clear communication, it is possible to create an experience that generates less stress and makes life easier for developers on your team, and even for other teams out there.

DX: Developer Experience in Design Systems was originally published in Lari Maza | En on Medium, where people are continuing the conversation by highlighting and responding to this story.

[clique aqui para português]

This is a post from a series where I share insights from my journey with JavaScript in a mini article format. See all other posts on my profile!

Among the numerous new features of ES6 is a new and useful operator. The spread operator, represented by the three-dot ellipsis ..., allows you to distribute the content of any iterable object into multiple elements.

For starters, a simple way to test this operator’s behavior is to use it just before a variable and log the result into the console. Let’s apply it to an array:

const names = ['Lestat', 'Marius', 'Akasha'];

console.log(...names);
// Lestat Marius Akasha

Note that the array has been separated, or spread, element by element.

The utilities of the spread operator in practice are broad. One of them is the possibility of combining arrays. See the example below:

const males = ['Lestat', 'Louis', 'Marius'];
const females = ['Pandora', 'Akasha'];

const characters = [...males, ... females];

console.log(characters);
// ['Lestat', 'Louis', 'Marius', 'Pandora', 'Akasha']

The end result stored in the variable characters is an array that combines the values ​​of the arrays males and females.

There is also a variation of this operator: the rest parameter. If we think of the spread operator as someone who takes elements out of a box and spreads them elsewhere, we might say that the rest parameter does the opposite: it collects scattered elements and stores them in a box.

The rest parameter syntax is also an ellipses ... and it allows us to represent an indefinite number of elements as an array. Let’s clarify this with an example:

const author = ['Anne Rice', 1941, 'USA', 'Interview With The Vampire', 'The Vampire Lestat', 'The Queen of the Damned'];

const [name, birth, country, ...books] = author;

console.log(name);
// Anne Rice

console.log(birth);
// 1941

console.log(country);
// USA

console.log(books);
// ['Interview With The Vampire', 'The Vampire Lestat', 'The Queen of the Damned']

Here, we use destructuring to retrieve the values ​​from the array author and assign them to isolated variables. Following the order of the elements, name, birth and country get the first three values ​​of the array, while books gets the rest (hence rest!) formatted as an array.

And finally, we can also use the rest parameter to represent an indefinite number of arguments in a variadic function — that is, a function that takes an infinite number of parameters.

Let’s use it to create a function that sums up any amount of numbers and returns the result:

function sum (...numbers) {
  let result = 0;
  for(const number of numbers) {
    result += number;
  }
  return result;
}

We can now call the sum() function with any number of parameters:

sum(1, 2);
// 3

sum(1, 10, 100, 100);
// 1111

That's all for today and see you next time ❤

JavaScript Pills: spread operator and rest parameter was originally published in Lari Maza | En on Medium, where people are continuing the conversation by highlighting and responding to this story.

[clique aqui para português]

This is a post from a series where I share insights from my journey with JavaScript in a mini article format. See all other posts on my profile!

ES6 brought a new way to extract data from arrays and objects to different variables called destructuring. Before that, extracting from an array was done like this:

const ages = [14, 28, 47];

const age1 = ages[0];
const age2 = ages[1];
const age3 = ages[2];

console.log(age1, age2, age3);
// 14 28 47

And extracting from an object was done like this:

const person = {
  name: 'Barbara',
  age: 36,
  job: 'Developer'
};

const name = person.name;
const age = person.age;
const job = person.job;

console.log(name, age, job);
// Barbara 36 Developer

Destructuring accomplishes the same task, but in a simpler and leaner way. Let’s go back and refactor the first example using this technique:

const ages = [14, 28, 47];

const [age1, age2, age3] = ages;

console.log(age1, age2, age3);
// 14 28 47

Wow, we turned three lines of code into one!

Observe the syntax of the second line, which is where the destructuring happens. On the left side, we use square brackets to indicate that we are destructuring an array; right there, we declare three variables at the same time, age1, age2, and age3, to save the extracted values. On the right side, we indicate that these values ​​shall be copied from the ages array.

We did not specify the indexes from which the values ​​should be extracted because they are no longer needed; now they implicitly follow the order of the elements in the array.

However, this does not mean we have to extract all values. You can ignore values ​​by leaving a blank space between commas, like this:

const ages = [14, 28, 47];

const [age1, , age2] = ages;

console.log(age1, age2);
// 14 47

In the example above, destructuring skipped the second index, which was dropped.

We can follow the same logic to extract values ​​from an object. Let’s try destructuring our previous object example:

const person = {
  name: 'Barbara',
  age: 36,
  job: 'Developer'
};

const {name, age, job} = person;

console.log(name, age, job);
// Barbara 36 Developer

Here, the curly braces {} indicate that the object will be destructured and the values ​​will be stored in the name, age and job variables. And on the right side, we state that the values ​​will be copied from the person object.

We did not specify the keys from which the values ​​should be extracted because, by naming the variables identically to the object keys, we let the destructuring match them and automatically store the value of the key name in the variable name. It’s like doing const name = person.name.

It's worth noting that this operation does not alter the original array or object — it just copies its values ​​to other variables.

That’s all for today and see you next time ❤

JavaScript Pills: destructuring was originally published in Lari Maza | En on Medium, where people are continuing the conversation by highlighting and responding to this story.

[clique aqui para português]

This is a post from a series where I share insights from my journey with JavaScript in a mini article format. See all other posts on my profile!

Today, we have three keywords for declaring variables in JavaScript: var, let and const. The keyword var has always been around, but let and const are ES6 additions. The last two have virtually eliminated the need for var, which has lately become discouraged. Let’s find out why!

The main highlight of using const is that this type of variable, as the name implies, is constant: it cannot be redeclared and its value cannot be reassigned (this does not mean it is immutable; it can still change through other manipulations). Therefore, the value of every const must be assigned in the same statement as it was declared, since we cannot assign it later. Here’s what happens when we try to perform an illegal reassignment:

const juice = 'orange';

juice = 'apple';
// Error: Assignment to constant variable

However, it is worth noting that, because it's not immutable, if const keeps an object, its keys and values ​​can be changed normally:

const myObj = { juice: 'orange' };

myObj.juice = 'apple';

myObj.juice
// 'apple'

Another difference between the three is that declaring a global variable (i.e. outside of a function) with var automatically adds it as a property of the window object:

var coffee = 'black';

window.coffee === coffee
// true

However, declaring a global variable with let or const does not add it to the window object:

let tea = 'green';

window.tea === tea
// false

In addition, both let and const declare a local variable within the scope of the block they are inserted into — unlike var, which ignores the block unless it is a function. A block is considered to be any brace {} delimited space. Here's an example of how let behaves in the scope of an if block:

let myNumber = 1;

if (myNumber === 1) {
  let myNumber = 2;

  console.log (myNumber);
  // 2
}

console.log (myNumber);
// 1

If we look it up from within the if block, the value of myNumber is the one that was assigned inside that block: 2. But if we reference it from outside the block, we have no access to the value that was assigned within it, since the variable is only available in that scope. We can only see the outside value of myNumber, attributed back at the example's first line: 1.

The same behaviour applies to const:

const myNumber = 1;

if (myNumber === 1) {
  const myNumber = 2;

  console.log (myNumber);
  // 2
}

console.log (myNumber);
// 1

This difference between scopes also affects the hoisting of the variables. Any variables declared with var are hoisted to the top of the function scope in which they were declared (or the global scope if they are not within any function). This means that the declaration (for example, var a) is executed before any other code, and even before the value is assigned:

function getMood (isHappy) {
  if (isHappy) {
    var happy = 'Yay!';
  } else {
    var meh = 'Meh';
  }
}

In the above function, if we analyse the hoisting of the variables, this is what is happening in practice:

function getMood (isHappy) {
  var happy, meh;

  if (isHappy) {
    happy = 'Yay!';
  } else {
    meh = 'Meh';
  }
}

Can you imagine how this behaviour can return many accidental undefined's (and migraines)?

Here comes a big advantage of the let and const variables: because they consider the block in which they were declared as their scope, they behave differently. If the variable is declared within a block, it is suspended in the “temporal dead zone” until the declaration is processed, instead of being hoisted to the top. Ergo, the variable can only be accessed after its declaration. Sounds safer, right?

We can link this context to yet another particularity of let and const: they cannot be redeclared in the same scope and any attempt returns a syntax error. However, redeclaration at different scopes is accepted, because one context does not see the other. Here’s an example of valid code with let foo declared in two different blocks:

let myValue = 1;

switch (myValue) {
  case 0: {
    let foo;
    break;
  }
  case 1: {
    let foo;
    break;
  }
}

When should we use each type of variable, then?

The decision between let and const depends only on whether you intend to reassign the value of this variable. Using const even improves the readability of your code by making it clear that such a variable is a constant.

In general: scoping, the ability to prevent value reassignment and the consequent reduced freedom in JavaScript (considered excessive by some) makes the use of let and const preferred by developers today to prevent accidental changes and breakage. The general convention is that there is no reason to use var anymore.

Keep in mind that there are still other differences and more advanced features. If you'd like to dive deeper, you should refer to the MDN specifications for let and const.

That’s all for today and see you next time ❤

JavaScript Pills: var, let and const was originally published in Lari Maza | En on Medium, where people are continuing the conversation by highlighting and responding to this story.

[clique aqui para português]

This is a post from a series where I share insights from my journey with JavaScript in a mini article format. See all other posts on my profile!

call() and apply() are very similar methods both used to pass a specific value of this to a function. They make it possible to determine the context from which the function will be executed.

Both methods can be invoked directly from a function. As an argument, we pass the object we want to use as the value of this; we may also pass other arguments that the function receives, if any. Consider the function and the object below:

function sayHello() {
  console.log('Hello, ' + this.name);
}

const user1 = {
  name: 'Paula',
  hobby: 'witchcraft'
}

If we want to apply the sayHello function to the context of the user1 object, we can do so with call(). We will not call the sayHello() function! We'll just reference it by name and then use dot notation to invoke the call() function method, passing the user1 object as an argument, which is the value of this we want to use. Let’s test this:

sayHello.call(user1);

// 'Hello, Paula'

Observe where the parentheses responsible for making the invocation are: the call() method executes the function, looking inside the user1 object to find the this.name value. At this point, the expression this.name is replaced by user1.name, which in turn is replaced by 'Paula'.

Now, let’s make things a little more interesting! Let’s test call() on a function that takes arguments:

function commentHobby(opinion) {
  console.log('I ' + opinion + ' ' + this.hobby);
}

const user1 = {
  name: 'Paula',
  hobby: 'witchcraft'
}

In addition to passing the user1 object again as the value of this, now we'll also pass the argument received by the commentHobby function to the call() argument list. Observe:

commentHobby.call(user1, 'love');

// 'I love witchcraft'

The result is exactly the same; the call() method invoked the commentHobby function using user1 as the value of this. This time, however, we also passed the 'love' string to replace the opinion argument.

What if we tried to use the call() method on a function that's inside an object — that is, a method? Yes: we can borrow a method from an object and apply it to another one!

Let’s create the kitty object and the puppy object:

const kitty = {
  race: 'cat',
  color: 'white',
  greet: function() {
    console.log("Hi, I'm a " + this.race);
  }
}

const puppy = {
  race: 'dog',
  color: 'black'
}

If we test the greet method as it is now, the value of this is the kitty object and therefore this.race is replaced with its value 'cat':

kitty.greet();

// "Hi, I'm a cat"

But if we have to borrow the greet method to apply to the puppy object, we can access the method from within the kitty object and use call() to invoke it in the puppy object:

kitty.greet.call(puppy);

// "Hi, I'm a dog"

At this point you may be asking: but what about apply()? Well, apply() has the exact same role: to call a function using the provided value of this, plus any other arguments if applicable. The difference is that, instead of comma-separated arguments, apply() receives the additional function arguments in an array.

Let’s test it in a function with more than one argument:

function sayWhere(city, country) {
  console.log ('I am ' + this.name + ' from ' + city + ', ' + country);
}

const user2 = {
  name: 'Lola'
}

Let's see what happens if we use apply() to apply the sayWhere function to the context of the user2 object, while also passing the arguments received by sayWhere in an array:

sayWhere.apply(user2, ['Paris', 'France']);

// 'I am Lola from Paris, France'

The use is very similar, isn’t it? When should we choose call() or apply(), then?

This depends on the type of arguments required in the function we want to use. apply() is especially useful when a function takes many arguments, or yet when we are not sure how many arguments exactly it will receive.

That’s all for today and see you next time ❤

JavaScript Pills: call and apply was originally published in Lari Maza | En on Medium, where people are continuing the conversation by highlighting and responding to this story.

[clique aqui para português]

This is a post from a series where I share insights from my journey with JavaScript in a mini article format. See all other posts on my profile!

An immediately invoked function expression, or IIFE, is a function called immediately after it is declared.

(function helloWorld() {
    alert('Hello, world!');
  }
)();

// alert 'Hello, world!'

In the example above, we wrap the function declaration in parentheses and add another pair of parentheses at the end, thus invoking the function immediately. We can also create an IIFE with an anonymous function:

(function() {
    alert("What's up?");
  }
)();

// alert "What's up?"

As we would when calling any function, we can also use the last pair of parentheses to enter arguments, like the example below:

(function(message) {
    alert(message);
  }
)("Let's go!");

// alert "Let's go!"

One of the main perks of the IIFE is that it can use its scope to create closure and prevent data inside it from being accessed. In practice, it works like this:

const myFunction = (
  function() {
    const password = 1337;

    return function() {
      console.log(password);
    }
  }
)();

// 1337

The function is executed immediately, as it is an IIFE. It returns an anonymous function, which is stored in myFunction and captures (or focuses) the password variable. This means that it holds the reference to its parent scope, like every nested function does.

Now we have in myFunction a private mutable state that cannot be accessed from outside the function. However, when we do console.log from within the returned function, we can access the password value!

There is also a different syntax for IIFE. We can move the second pair of parentheses into the first pair, thus wrapping the entire expression with the first pair of parentheses:

(function bark() {
 alert('Woof!');
} ());

This is just a style choice, as the result is identical.

It is noteworthy that placing these variables in closed scopes not only has its advantages in data security; if fewer variables are created globally, we reduce the noise and chance of conflicting their names.

That’s all for today and see you next time ❤

JavaScript Pills: immediately invoked function expression (IIFE) was originally published in Lari Maza | En on Medium, where people are continuing the conversation by highlighting and responding to this story.

[clique aqui para ler em português]

This is a post from a series where I share insights from my journey with JavaScript in a mini article format. See all other posts on my profile!

A function that returns another function is a type of higher order function. Observe the example below:

function outerFunction() {
  alert('Hello!');

  return function() {
    alert('Can you hear me?');
  };
}

Despite what it may seem, if we simply call the outer function with outerFunction(), we will only see the first alert 'Hello!'; the inner function code will not be executed. We’ll need a specific trick if we want to trigger the second alert!

There are two ways to execute the returned function. One option is storing the external function outerFunction in a variable. Behind the curtains, we are actually storing the return of the function this way:

const innerFunction = outerFunction();

Now, we can call this new variable like any other function and only the returned function will be executed:

innerFunction();
// alert 'Can you hear me?'

Another alternative is calling the function immediately, without the need to create a variable. Just add another set of parentheses to the external function call:

outerFunction()();
// alert 'Hello!' and then alert 'Can you hear me?'

Note that the effect in this case is different from the first example. Here, the first pair of parentheses executes the outerFunction function and returns the inner function, which is then called by the second pair of parentheses!

We must choose an approach by assessing whether or not we want to execute the external function content before the returned function content is executed.

That’s all for today and see you next time ❤

JavaScript Pills: function that returns another function was originally published in Lari Maza | En on Medium, where people are continuing the conversation by highlighting and responding to this story.

[clique aqui para ler em português]

This is a post from a series where I share insights from my journey with JavaScript in a mini article format. See all other posts on my profile!

Consider an object called shirt with a key named color storing the string 'blue':

const shirt = {

  color: 'blue'

}

If we had to access the value of color, we could either use the bracket notation shirt['color'] or the dot notation shirt.color. Both choices are equivalent, right? Hold that thought!

Let’s now create a variable and save the string 'color' inside it:

const myVariable = 'color';

Now, we can also use this variable to access the color value within the shirt object. We will first try the bracket notation. Watch this:

shirt[myVariable];

// 'blue'

This is possible because, when executing this code, the myVariable variable is replaced with its content, which is the string 'color'. In practice, we are doing shirt['color'].

Ok, that makes sense! But just out of curiosity, let’s try this same type of access using the dot notation?

shirt.myVariable;

// undefined

…Uh, what? Undefined? What happened here?

It gets easy to spot the difference between both scenarios if you know this basic concept about JavaScript objects: underneath the curtain, all keys in an object are strings, even when the quotation marks are omitted — which is our case.

When running shirt.myVariable, we are requesting JavaScript to find a key inside shirt which corresponds to the string 'myVariable', which doesn’t exist. In practice, that was exactly the same as doing shirt['myVariable'].

However, if you go back to using the bracket notation with shirt[myVariable], JavaScript doesn’t coerce (convert) the bracket contents into a string and looks for the variable instead — which is the behavior we expect.

That’s all for today and see you next time ❤

JavaScript Pills: accessing object keys using external variables was originally published in Lari Maza | En on Medium, where people are continuing the conversation by highlighting and responding to this story.

[click here for English]

DX, ou Developer Experience, é uma disciplina que descreve a experiência de uma pessoa desenvolvedora ao utilizar um produto. De forma análoga à UX (User Experience), uma boa DX faz toda a diferença na aceitação e no potencial de divulgação do seu produto, seja ele uma API, uma biblioteca, uma ferramenta ou um serviço. A conscientização sobre esse assunto tem crescido tanto que já existe até trabalho especializado — a bio do Twitter da dev Sarah Drasner diz "Head of DX @ Netlify".

Na minha experiência desenvolvendo o Astro, design system da Magnetis, a qualidade da DX é bastante relevante para impulsionar a produtividade do cliente interno. Essas pessoas podem ou não ser colaboradoras da Magnetis, uma vez que o Astro é open source — o que significa que a responsabilidade é ainda maior.

Com base nesse aprendizado, trago alguns pontos de atenção para melhorar a DX do seu projeto:

1. Documentação

Parece até um pouco óbvio mencionar a documentação como um ponto principal de atenção na DX; mas, para um texto que muitas vezes será a única via de comunicação com a pessoa usuária, ele raramente recebe a atenção que merece.

Em projetos e repositórios abertos ou fechados, alguns mantenedores esperam que os usuários entendam tudo apenas lendo o código — o que não só é uma comunicação ruim, mas também uma falha de empatia. E dentro de times, a solução para projetos mal documentados muitas vezes é perguntar pra alguém, o que também é ruim para ambos os lados.

A documentação é sua oportunidade de explicar com linguagem humana a finalidade e a forma de uso do seu projeto. Aqui, você deve ensinar a usar o design system, mas também a contribuir para o código dele (ainda que não seja open source, novas pessoas podem vir trabalhar no projeto a qualquer momento). Pense nesses momentos separadamente — você pode até criar dois arquivos separados no GitHub, como fizemos no repositório do Astro com "Readme" (guia de uso) e "Contributing" (guia de contribuição).

Não entrarei em detalhes sobre como escrever uma boa documentação porque já escrevi um artigo sobre isso, mas, em resumo, ela deve contemplar esses três A's:

• Abrangente: Certifique-se de que o documento cobre todas as dúvidas que possam surgir sobre como funciona o projeto. Explique o que ele faz, como instalar, como usar, e inclua soluções de problemas conhecidos. Seu objetivo aqui é anular a necessidade de te contatar diretamente pra tirar dúvidas. Não seja um gargalo. A fonte da verdade (Single Source of Truth) deve ser a documentação, e não você.
• Acessível: Não assuma que toda pessoa que ler o documento tem o mesmo nível técnico que você, mesmo que você ache que tem um nível técnico baixo (alô, síndrome do impostor!). Evite termos técnicos quando possível. Escreva tutoriais passo a passo. Não assuma que a pessoa sabe clonar um projeto ou instalar dependências via terminal, por exemplo. Explique para um iniciante e você estará explicando para todo mundo.
• Amigável: Ler documentação pode ser uma atividade maçante, então tente não deixá-la desnecessariamente longa. Existe uma diferença entre abrangente e prolixo. Vá direto ao ponto, use um tom amigável e, se quiser, pode até incluir um toque de humor.

2. Padrões de uso

No caso do Astro, o design system é utilizado aplicando classes CSS a uma estrutura de markup exemplificada na documentação. Eis um exemplo abaixo:

Tentamos criar nomes de classes que sejam descritivos para humanos, em vez de algo como a-bt--ur__md1, ainda que fiquem mais longos; queremos que sejam auto explicativos e memoráveis, o que diminui a confusão e a necessidade de consultar a documentação repetidamente.

Outro ponto importante é que os nomes de classe precisam ser mais específicos (como a-btn) em vez de totalmente genéricos (como btn) para evitar conflitos com o CSS existente em projetos legados. O objetivo aqui é gerar o mínimo de efeitos colaterais na importação do design system, e deve-se aplicar essa mentalidade a todos os pontos do projeto que se possa identificar.

Por fim, para criar um sistema escalável e previsível, é preciso tentar manter um padrão de uso que faça sentido. Esse é um grande desafio quando recebemos demandas de design que fogem à norma, e pode ser necessário negociar para satisfazer essas demandas enquanto se mantém também a consistência.

Por exemplo: no Astro, temos muitas variantes de estilos de botões e cada uma delas tem quatro cores. O design system tende a escalar, e, quando introduzirmos novas cores ou estilos, queremos seguir o padrão e até tentar facilitar a manipulação desses botões com menos consultas à documentação.

Para isso, criamos uma estrutura de classes que variam de forma previsível. a-btn--uranus é o botão primário na cor azul (que nomeamos "uranus"). Nas outras variantes, acrescentamos um modificador que pode ser a-btn--outline-uranus para o botão outline ou a-btn--ghost-uranus para o botão ghost.

Além disso, a cor "uranus" pode ser trocada por qualquer uma das outras variantes ("mars" pra vermelho, "venus" pra rosa ou "earth" pra verde) em qualquer um dos botões, que o resultado é previsível.

E para definir o tamanho, acrescentamos obrigatoriamente uma das três classes de tamanho: a-btn--small, a-btn--medium ou a-btn--large. Independente de qual for o botão, o resultado é sempre o mesmo.

Eis um vídeo demonstrando a troca desses modificadores (abra em uma nova aba):

demo.webm

Criando padrões e previsibilidade, o uso fica mais intuitivo, à prova de erros e diminui a dependência da documentação.

3. Tecnologias

Além dos pontos que cobrimos, nos critérios de uma boa DX ainda pesam as consequências das decisões técnicas, como a facilidade de uso, o peso do pacote e as barreiras para utilizar e contribuir.

Tente prezar pela simplicidade pura e evitar complexidade desnecessária. Às vezes, precisamos mesmo de novas ferramentas para escalar o projeto. Mas não deixe de questionar se aquilo é mesmo necessário. Por exemplo, se for possível escrever CSS sem nenhum framework, escreva — é mais viável do que parece. Cada camada que acrescentamos na stack, ainda que nos pareça familiar, pode criar uma barreira para quem não tiver contexto daquela tecnologia específica. É uma questão de empatia e inclusão, mas também de permitir que mais pessoas se agreguem ao seu projeto, usando ou contribuindo.

Faça o seu melhor para não lotar seu projeto de dependências. Cada uma delas requer atualizações no futuro, o que pode quebrar o projeto e gerar trabalho para adaptá-lo, além de ser uma potencial porta para vulnerabilidades. Não perca o controle.

Continue tentando automatizar todos os processos manuais que você conseguir. Por exemplo, em vez de pedir para importar fontes tipográficas ou ícones manualmente, inclua-os no pacote do projeto e crie formas simples de chamar esses assets. Tente aplicar o conceito de "zero configuração".

Teste a velocidade para baixar e rodar o projeto, e busque melhorias nesse processo também.

Em resumo, um design system (ou qualquer projeto) com uma boa DX é um sistema fácil e agradável de usar e de contribuir. Com partes iguais de qualidade técnica e comunicação clara, é possível criar uma experiência que gere menos stress e facilite a vida de desenvolvedores no seu time, e até de outros times por aí afora.

Update em 28/9/19: Escreva um Guia de Atualização quando houver breaking changes

Recentemente, o Astro lançou a versão 2.0.0 com breaking changes — isso é, com alterações incompatíveis que podem causar quebras nos projetos em que a dependência está instalada. Nesse caso, o motivo é que mudamos algumas classes CSS e o nome de alguns ícones.

Atualizar uma dependência nessas condições requer atentas adequações no projeto para evitar surpresas desagradáveis. O que você pode fazer para melhorar a DX?

• Tenha sempre consciência de alterações que podem causar quebras e pese os benefícios antes de prosseguir. Planeje a nova versão de modo a isolar a incompatibilidade e causar o mínimo de efeitos colaterais;
• Quando lançar essa versão (que será major, segundo o Semantic Versioning), escreva um Guia de Atualização mapeando todas as alterações que os desenvolvedores precisam fazer em seus projetos que utilizam o design system. Veja o Update Guide da v2.0.0 do Astro aqui como um exemplo.

DX: Developer Experience em Design Systems was originally published in Lari Maza | PT-BR on Medium, where people are continuing the conversation by highlighting and responding to this story.