DEV Community: Victor Garcia Dev

How to Dockerize a React App and Deploy It Easily

Victor Garcia Dev — Wed, 01 Nov 2023 14:28:22 +0000

Do you want to learn how to dockerize a React app and make it ready for deployment? In this article, I´ll show you how to do that with a practical example from my GitHub repo.

Originally published at MentorCruise: How to Dockerize a React App and Deploy It Easily - MentorCruise

Prerequisites

Ensure you have a foundational understanding of React, Docker, and basic shell scripting. Ensure Docker and Node.js are installed on your machine, and you have a code editor ready for some hands-on action!

Understanding the React Application Structure

The React application in our repository is structured with various components, dependencies, and configurations. The app is a simple goal tracker that lets you add, edit, and delete your goals. It uses React Hooks, React Router, and Axios to create a dynamic and interactive UI. The app also communicates with a backend API that uses MongoDB as the database. The apps structure is as follows:

package.json: This file defines the dependencies and scripts for the app. We use libraries such as react, react-dom, react-router-dom, axios, and bootstrap.
src/index.js: This file renders the main App component and wraps it with a BrowserRouter component to enable routing.
src/App.js: This file defines the App component, which contains the main layout and logic of the app. It uses useState and useEffect hooks to manage the state and fetch data from the API. It also uses Switch and Route components to render different pages based on the URL path.
src/components: This directory contains the reusable components for the app, such as GoalList, GoalForm, GoalItem, Navbar, and Footer. Each component has its file with a .jsx extension.
src/pages: This directory contains the components for the different pages of the app, such as Home, About, and NotFound. Each page has its file with a .jsx extension.
src/styles: This directory contains the custom CSS styles for the app. We use Bootstrap as a base framework and override some styles in our files.

Crafting a Multi-Stage Dockerfile

The Dockerfile in the frontend directory employs a multi-stage build to create an optimized Docker image:

Stage 1: Building the React Application
Utilizes node:16.3.0-alpine for a lightweight build environment. Installs dependencies and builds the application using npm.
Utilizes node:16.3.0-alpine for a lightweight build environment.
Installs dependencies and builds the application using npm.
Stage 2: Setting Up the Nginx Server
Adopts nginx:alpine to serve the built React application. Copies the build artifacts and custom Nginx configuration for serving the application.
Adopts nginx:alpine to serve the built React application.
Copies the build artifacts and custom Nginx configuration for serving the application.

Parameterizing Nginx Configuration

The custom Nginx configuration (custom-nginx.template) is designed to proxy API requests to a backend service and serve the React application for other routes. A shell script (generate-config.sh) dynamically generates the final Nginx configuration by substituting environment variables, providing flexibility to define the backend host at runtime.

Orchestrating Containers with Docker Compose

Docker Compose is a tool that lets you define and run multiple containers using a YAML file. It simplifies the process of building, running, and connecting containers.

The docker-compose.yaml file orchestrates the frontend and backend services, ensuring they can communicate and are deployed cohesively:

Local Development & Testing

To run the Dockerized React app locally, use docker-compose up to build and start the containers. Ensure the application communicates with the backend API effectively, and debug using Docker logs and browser developer tools.

CI/CD Considerations for Dockerized React Apps

Integrating CI/CD pipelines, like GitHub Actions, can automate the build, test, and deployment of the Dockerized React app. Define workflows in .github/workflows to trigger code pushes or pull requests, ensuring continuous delivery and integration.

Build Workflow

This workflow triggers every push or pull request to the main branch. It builds and tests both frontend and backend images using Docker commands. It also pushes the images to a Docker registry (such as Docker Hub or GitHub Packages) using secrets to store credentials. We have commented it out on our repo to avoid additional build runs. The code we've used is the following:

Best Practices & Tips

Optimize Dockerfile: Leverage Docker layer caching by ordering instructions to install dependencies before copying all source files.
Manage Images: Regularly prune unused Docker images and containers to manage disk usage.
Security: Ensure only necessary ports are exposed and use trusted base images.

Conclusion

I hope you enjoyed this guide on how to dockerize a React app and make it deployable. You learned how to use Docker, Nginx, and Docker Compose to set up a uniform environment for your app in different phases of development, testing, and production. This will help you streamline your DevOps process and create better software.

If you liked this article, you can check my other blog posts and my mentorships plans at my MentorCruise Profile.

Thanks for reading!

References

Source code: GitHub repository

Jmeter API Tests from Postman Collection using Loadium

Victor Garcia Dev — Wed, 06 Oct 2021 15:32:04 +0000

In the previous article of this series, we learned how to create a Postman collection from our OpenAPI documentation.

Check out the complete series if you missed it!

Today we will see in this brief tutorial how to create a Jmeter test suite from our collection using Loadium

Import the collection to Loadium

Our test suite will be generated from the Postman collection in the previous chapter. We have all the CRUD functionality of our Idea API if you remember.

Let's export our collection into JSON.

Right click on the collection
Select Export
Select Collection v2.1 (recommended)
Click again on Export

Now, we have to open a browser and go here. You could also go to the main Loadium site. There, select the Features tab, and click on the Convert Postman to Jmetersection.

It will require you to log in. You could use Google, Github, or Linkedin for doing so, so no worries! After the login process, the home section will appear. Select Convert to .JMX option, the last one on the left.

When the form pop-up appears, select the default option POSTMAN. Then drag your exported collection file to the drop zone. Now your file will be successfully generated. Click in Download JMX.

Install Jmeter

To install Jmeter, you should follow these steps provided by this Blazemeter article

Download Releases

Install the most recent 64-bit Java Runtime Environment (JRE) or Java Development Kit (JDK). Because JMeter is a pure Java program, this is critical.
Go to the Apache JMeter website and look for the Binary to save to your PC.
Move this file to your desired location after downloading it. Unpack it, then go to the folder, then the bin directory.
Take a peek around. A set of scripts should appear that can run JMeter in various modes.

For me, I have to run on my Ubuntu terminal

./jmeter

and the GUI will appear before my 👀👀

Don't be afraid of the installation process. Is quite easy although it is not very frequent

Load our JMX and Refactor

Now we are only a few steps from the glory! 🥳🥳

Let's add our JMX file by selecting File -> Open and navigate to the location of your downloaded JMX file.

Now you should see the testing suite loaded in JMeter

We have to make some refactoring to make it work. If you click on one of the requests, you would see something like this:

We have to make the following changes:

Split the baseUrl into Protocol - Host - Port
Refactor the :ideaId parameter into JMX Syntax

Defining default HTTP request Options

First, we will add some basic variables for configuration. To include a config element, let's right click on the engine wheel and select Add -> Config Element -> User Defined Variables

We will include two elements:

defaultPath: the prefix path for requests -> /victorgarciar/idea-api/1.0.0
server: the domain of our mock server -> virtserver.swaggerhub.com

We want to configure the HTTP server once and inherit it on each request. To do so, we have to create an HTTP Request Defaults element by right-clicking on the engine wheel and selecting Add -> Config Element -> HTTP Defaults.

We have to add the server variable. Left the port empty as we are using the 89. It results as follows:

Refactoring Postman syntax to JMX

We have to refactor the ideaId parameter so that it fits the Jmeter syntax. You can click on Search -> Search or the shortcut Ctrl+F. The search panel will appear.

Now all we have to do is to change all the :ideaId to ${ideaId}

Let's include an example ideaId value to our user variables. We could add it dynamically using JSON assertions, but it is out of the scope of the tutorial. If you want more info about it, check this article.

The resultant User variables would be:

Finally, we have to add the defaultPath variable to each of the requests (I know, this is a heavy con 🥲🥲). If you find out any alternative, please let me know in the comments!

Add some assertions

We have our requests but, HOW THE HECK WE KNOW THEY ARE WORKING AS EXPECTED !?!?!?

Use assertions

Let's add some assertions to the requests.

Right Click on any of the requests and select Add -> Assertions -> Response Assertion
Select the Response Code and add the value 200
Change the Pattern Matching Rules to Equals

You can copy and paste the assertion to all the requests by doing Ctrl+C to the element, selecting the target request, and Ctrl+V.

Finally, we have to add a listener to the end of the suite to have a summary of the results of our testing process.

Click on the engine and select Add -> Listener and add both View Results Tree and Assertion results.

These two are the ones I use the most for testing myself. One will show you the data of the requests/response, very useful for debugging. The other one will show you the results of your assertions. The results tree would show anything different from a 2XX code as an error, but you may want to test error cases. That's when the Assertion results come in handy.

Lauch your test suite

Now we are ready to test! 🥳🥳

We didn't make a single line of code, remember. So, have to use the mock server we created in a previous article. For using it we have to set up the HTTP Request options to:

Protocol: HTTPS
Server: domain of your mock server. In my case ``
Port: Empty or 80. It's the same.

Let's launch it!! Go and click on the RUN button in the toolbar.

You should check your assertions and see EVERYTHING IS GREEN 💚 (Mock's magic 🪄🪄)

And that's it! You have created a test suite for your API design!

I know there are some alternatives like Newman which I have to test yet. But I find Jmeter to be very complete, as we have additional options, out of the scope of the article like:

Checking DB rows
Checking Redis/Cache status with custom Beanshell scripts
JSON Assertions
Way other things I don't know 😁😁

Summary

In this article, I hope you have learned:

Convert your Postman collection to a JMeter file using Loadium
Install Jmeter
Configure a Jmeter file and add assertions
Execute a Test Suite in Jmeter

I am HONOURED if you have reached this point. Thanks a lot for reading 💙

Hopefully, I was able to explain how to create a Jmeter test file from a Postman, configure, and run it!

Reach out on Twitter to find more valuable content or just chatting!

🐦 @victorgarciadev

😼 github.com/victorgrubio

References

Thanks and Keep It Up! 🦾🦾

How to create a Postman Collection from OpenAPI Docs

Victor Garcia Dev — Tue, 28 Sep 2021 09:39:10 +0000

In the previous article of this series, we learned how to create the documentation for your API using OpenAPI.

If you didn't check it out, what are you waiting for !?!? 😁😁

Today we will see in this brief tutorial how to create a Postman collection from this documentation.

Download API docs

We have different ways to download the YAML file containing the documentation. It depends on how we stored it.

Swagger Editor

Swagger Editor stores the status of your last edition. Yet, if you have to delete information from your browser, all your progress may be lost! 🆘🆘

Swagger Editor is an excellent tool for fast edition and linting your files. However, if the documentation is large and will take you days, then use editors like Notepad++, Gedit, or VSCode to write it.

To download the API documentation file from Swagger Editor, we have to click on: Edit-> Save as YAML

The browser will download an openapi.yaml file.

SwaggerHub

Swagger Hub stores the information on their servers. There is nothing to worry about here 🤗 To download it, we have to click on our API project.

Once we are editing our project, we have to click on Export -> Download API -> YAML Resolved.

I think this is the best format to do so. JSON will be valid as well, although I find YAML easier to edit.

Import it to Postman

Now, go on and open Postman. If you don't have it, you can download it from this link.

We are going to select the APIs tab.

Then let's click on Import and select the OpenAPI docs file. Confirm that you want the Collection to act as Documentation

If you check the APIs section, the definition of your OpenAPI Documentation should appear.

Moreover, the generated collection will appear in the Collections tab. You should see something like this:

Create a Mock Server in Swaggerhub

Do you have a server to make requests to? NO? LET'S MOCK IT THEN!

Before testing our API, we have to create a Mock Server to make requests to! To do so, we are going to take advantage of the Integrations available at SwaggerHub.

Click on your API name inside the editor and delete Integrations tab.

Then, add new integration and select API Auto Mocking

Set your API name to whatever you want. In this case, I defined Idea API.

Now the integration is completed. We have our mock server up and running! The address has the following format:

https://virtserver.swaggerhub.com/<owner>/<api-name>/<version>

In my case, this results in https://virtserver.swaggerhub.com/victorgarciar/idea-api/1.0.0

Test!

You can't say "It works!" if you haven't tested it yourself

Let's go back to our Postman Collection and set the "baseUrl" variable to the URL of our mock server.

Click on the Collection's name and select the Variables tab. You will have a variable there named "baseUrl" as mentioned. Delete the current value and paste your mock server URL!

Now we have everything set up! Go to one of the requests and send it. You should see something like this:

Of course, results will make no sense since we are using a mock server. Don't forget!

Summary

In this article, I hope you have learned:

Downloading your API docs
Importing it to Postman
Creating a mock server in SwaggerHub
Test your API with a mock server

I am HONOURED if you have reached this point. Thanks a lot for reading 💙

Hopefully, I was able to explain how to import OpenAPI docs to Postman and create a Mock Server in SwaggerHub to test it!

Reach out on Twitter to find more valuable content or just chatting!

🐦 @victorgarciadev

😼 https://github.com/victorgrubio

References

Thanks and Keep It Up! 🦾🦾

API Documentation with OpenAPI

Victor Garcia Dev — Mon, 27 Sep 2021 17:49:52 +0000

Your backend needs an API to expose all its value to the world. You already know that. And it should be well commented to avoid any user misusing or hate to use it.

An API can be considered as the contract between the information provider (a lovely backend developer, like me 😇) and the consumer (an awful frontend developer, like me 😈). There, the content required for the producer ( request ) to provide the information that the consumer needs ( response ) is defined.

There we hide all of our terrible backend logic from our users and give them a nice, simple way to use our services. And, if it is in exchange for money, better 💸💸💸

OpenAPI

Okay Victor, I know a little bit about APIs, maybe I even know how to create one ... BUT HOW THE F DO I DOCUMENT IT?

Nice question. Tons of people did the same one. Some of them united and created the OpenAPI Specification (OAS).

The OpenAPI Specification defines a standard, language-agnostic interface to RESTful which permits both people and computers to find and get the value from the services without getting to source code or documentation. If defined properly, users can understand and interact with the remote service with a low effort from their site. I mean, at least they need access to the Internet 😅😅

An OpenAPI file allows you to describe your entire API, including:

Available endpoints (/ideas) and methods on each endpoint (GET /ideas, POST /ideas)
Operation parameters Input and output for each method
Authentication methods
Contact information, license, terms of use, and other information.

Documentation-First vs Code-First Workflow

To code first or to document first, that is the question

I have created quite a few APIs, most of them using API documentation. Some developers like to create the OpenAPI file from the development. Most programming languages and frameworks have a plugin to generate OpenAPI documentation from your code.

A list for some of the most used:

There is another way to view it. Automatically creating your code from the documentation.

As OpenAPI doesn't care about your programming language, it is able to generate code from the YAML/JSON file to the framework you specify. Then, you just need to create the server logic and your API is ready to go!

Some useful tools that allow you to generate code from the documentation:

OpenAPI Generator - Open Source Tool to create client/server versions of our API
Swagger Online Editor - Edit & Lint your OpenAPI files
SwaggerHub - Design & Publish your documentation
Swagger Codegen - A Swagger tool to generate client libraries for your API in over 40 languages and generate a server stub for your API.

Create an OpenAPI documentation file

Let's make an example to learn

Idea API

To illustrate most of the concepts without creating a difficult logic, let's create an Idea API.

This will be a simple Create Read Update Delete (CRUD) API, with just the Idea as a model (no users or anything like that)

Definition & Concepts

First, go to [Swagger Online Editor]. It will show the classic PetStore Example using Swagger 2.0. We will like to convert this example to OpenAPI v3.

To do so, click on Edit -> Convert to OpenAPI 3

Now let's delete most of it, leaving only the top part, without any paths:

openapi: 3.0.1
info:
  title: Swagger Petstore
  description: 'This is a sample server Petstore server. You can find out more about Swagger
    at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For
    this sample, you can use the api key `special-key` to test the authorization filters.'
  termsOfService: http://swagger.io/terms/
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
servers:
- url: https://petstore.swagger.io/v2
- url: http://petstore.swagger.io/v2
tags:
- name: pet
  description: Everything about your Pets
  externalDocs:
    description: Find out more
    url: http://swagger.io
- name: store
  description: Access to Petstore orders
- name: user
  description: Operations about user
  externalDocs:
    description: Find out more about our store
    url: http://swagger.io
paths:
components:
security:

Let me describe all the keys used in the previous piece of documentation

As mentioned before, you have a detailed explanation in the OpenAPI Documentation

You will see alerts in the editor. No worries, we have to define our methods yet.

These methods are the services we allow the users to interact with. As some of you may know the most common HTTP methods are:

GET -> Retrieves information
POST -> Send loads of data to a server to create or update a resource
PUT -> Complete update of an object
PATCH -> Partial update of an object
DELETE -> Remove object

Other additional methods, less common but also important:

HEAD -> Equal to GET, without receiving response items (Check that GET works)
OPTIONS -> Returns data describing what other methods and operations the server supports at the given URL

A detailed article about HTTP methods is available here, as it is out of the scope of this one.

Endpoint Creation & Parameters

As mentioned before, we are going to use GET, POST, PUT and DELETE methods for our API.

Let's create the List and Create endpoints:

openapi: 3.0.1
info:
  title: Idea API
  description: 'This is a sample server for the Idea API from the blog post "API Documentation with OpenAPI" by @victorgarciadev'
  termsOfService: http://swagger.io/terms/
  contact:
    email: victorgrubiodl@gmail.com 
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.0.0
externalDocs:
  description: Blog with amazing articles
  url: https://www.victorgarciar.com
servers:
- url: https://petstore.swagger.io/v2
tags:
- name: ideas
  description: Everything about your Ideas
paths:
  /ideas:
    get:
      summary: List all ideas
      description: Retrieves a list of all the ideas available
      tags:
       - ideas
      responses:
       "200":
          description: List of ideas
          content:
            application/json:
              schema:
                type: array
                items:
                 $ref: '#/components/schemas/Idea'
       "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                 message: 
                   type: string
                   description: Error message
                   example: 'This is an error message for Internal Server Error'
    post:
      summary: Create idea
      description: Creates a new idea from its basic data
      tags:
       - ideas
      requestBody:
        description: Data from idea that will be created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Idea'
            example:
              description: Idea to create
      responses:
       "200":
          description: The created idea
          content:
            application/json:
              schema:
               $ref: '#/components/schemas/Idea'
       "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                 message: 
                   type: string
                   description: Error message
                   example: 'This is an error message for Internal Server Error'
components:
  schemas:
    Idea:
      type: object
      description: Idea
      properties:
       id: 
        type: integer
        description: id of item
        minimum: 1
       description:
        type: string
        description: Description of idea

And that should render to something like this

NOTE: You can observe that we have refactored the metadata of our API to be adjusted to this project.

Now let's create the Read, Update and Delete endpoints. Below the definition of the /ideas path, add the following code:

/ideas/{ideaId}:
    get:
      summary: List all ideas
      description: Retrieves a list of all the ideas available
      tags:
       - ideas
      parameters:
        - name: ideaId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
       "200":
          description: Idea requested
          content:
            application/json:
              schema:
                 $ref: '#/components/schemas/Idea'
       "404":
          $ref: '#/components/responses/404NotFound'
       "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                 message: 
                   type: string
                   description: Error message
                   example: 'This is an error message for Internal Server Error'
    put:
      summary: Updates an idea
      description: Performs an update of an specific idea by the data provided
      tags:
       - ideas
      parameters:
        - name: ideaId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Data to update the idea
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Idea'
            example:
              description: Idea to update
      responses:
       "200":
          description: Updated idea
          content:
            application/json:
              schema:
                 $ref: '#/components/schemas/Idea'
       "404":
          $ref: '#/components/responses/404NotFound'
       "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                 message: 
                   type: string
                   description: Error message
                   example: 'This is an error message for Internal Server Error'
    delete:
      summary: Deletes an idea
      description: Removes an idea if exists
      tags:
       - ideas
      parameters:
        - name: ideaId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
       "200":
          description: Empty body for ok
          content:
            application/json:
              schema:
                type: object
       "404":
          $ref: '#/components/responses/404NotFound'
       "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                 message: 
                   type: string
                   description: Error message
                   example: 'This is an error message for Internal Server Error'

Here we can see that we have included a parameter. They can be either specified in the same method (Read Method) or we can create a reference to them in the Parameters section of the documentation (Update Method)

Model Definition & Object Reference

As you may observe, request bodies and responses include a reference to an Idea object. In the schemas' part, we define all the objects we may use for our bodies and responses. This will create a much more organized structure and reduce duplicities.

A Schema contains the following properties:

Summary -> Brief description of the object
Description -> Complete information about the model
Required -> List of required properties for the model
Properties -> List of attributes of the model
Example -> Object used to complete the documentation as default. Could be one or more. Documentation

A more detailed explanation about attribute types and object creation can be found in the OpenAPI Section

An example would be the Idea model

    Idea:
      type: object
      description: Idea
      properties:
       id: 
        type: integer
        description: id of item
        minimum: 1
       description:
        type: string
        description: Description of idea

We can reference it in the documentation with the following code:

              schema:
                 $ref: '#/components/schemas/Idea'

This applies also to responses and parameters:

   delete:
      summary: Deletes an idea
      description: Removes an idea if exists
      tags:
       - ideas
      parameters:
        - name: ideaId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
       "200":
          description: Empty body for ok
          content:
            application/json:
              schema:
                type: object
       "404":
          $ref: '#/components/responses/404NotFound'

  responses:
    404NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
             message: 
               type: string
               description: Error message

          example: 'Idea with id requested not found in server'

More info about referencing here

Security

We are going to add a simple API Key security layer for the sake of completeness. To do so, we are going to define a Security Schemes property at the root of the document

The security schema may vary in type depending on your project's conditions. We can define the security in a more granular way by specifying it on each method.

We have to add the API Key auth to the securitySchemes property at Components. Then add the security property, at the same level of paths, components, etc.

  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
security:
  - apiKey: []

More info about Security Schemes in OpenAPI here.

Share it online with SwaggerHub

Someone may use your API one day. Go on and share it!

Now that we have our API ready, let's share it with everyone. As you may know, if you follow my Daily Dev Tips from Twitter, I like a lot Swaggerhub to define and expose our API documentation.

Let's create a new Project there, checking Import and document API

Then, we can download our OpenAPI documentation file from Swagger Editor and add it to the project

And it's done, we have our API documentation published for everyone to see. Here's mine

Summary

We have (I hope) learned in this article:

What's an API
Why is important to document your APIs with OpenAPI
How an OpenAPI documentation file looks like
Implement OpenAPI documentation for a CRUD API
Share it using Swaggerhub

I am HONOURED if you have reached this point. Thanks a lot for reading 💙

Hopefully, I was able to explain the importance of API documentation and how to do it using OpenAPI.

Reach out on Twitter to find more valuable content or just chatting!

🐦 @victorgarciadev

😼 https://github.com/victorgrubio

References

Thanks and Keep It Up! 🦾🦾

Unleash Your Learning Potential through Writing

Victor Garcia Dev — Fri, 17 Sep 2021 13:40:01 +0000

Many of us may have tried to start technical writing and left it after a week. Perhaps you've created a blog but stopped posting after a year. You might have wondered if you would ever be the one offering valuable replies on Stack Overflow.

If you can relate to these experiences, allow me to share my main motivation for writing:

Writing helps me learn better

Traditional Learning Methods

Let's face it, traditional learning methods often fall short. During my college years as a Telecommunications Engineering student, I had to absorb a lot of information in a limited time frame. Picture this: 8 exams in just 4 days. It was intense. Initially, I relied on memorizing exercises from previous years and regurgitating fixed patterns. And it worked for a while.

What would I do? What they have educated me for: Try to learn how to do some exercises from previous years. Memorize the parts that are always asked the same way.

It worked for a while

However, everything changed when I pursued a Machine Learning master's degree. The complex math I encountered demanded a deeper level of understanding. Thanks to exceptional teachers, I shifted my focus to grasping concepts and truly comprehending them. The knowledge gained during that period remains etched in my mind.

Here is when everything made sense.

Overcome the Tutorial Syndrome

We were born in the era of YouTube, where countless videos exist on practically every topic imaginable. Content creators possess an infinite wealth of knowledge at their fingertips. But let's pause and reflect: How much of that content do we retain after three days? I remember very little. Please don't misunderstand meI appreciate YouTube and the incredible free content it offers.

However, watching videos, reading books, and scrolling through posts are all passive activities. They require less attention compared to activities like coding. On occasion, I've stumbled across intriguing concepts in books that have fascinated me and triggered a surge of dopamine. Yet, more often than not, those highlighted passages quickly fade from memory. In contrast, lines of code and text that I've created through sweat and perseverance tend to leave a lasting impression.

Enhancing Understanding of Topics

Name a topic that writing didnt help you understand better. It's hard, isn't it?

Let me share an example from my own experience. I was reading "Head First Design Patterns"a highly recommended book. Each chapter delved deep into one or more design patterns. Although I read it almost every day, after a week, I realized I couldn't recall any of the patterns or how to apply them.

That's when I decided to tackle a different approach. I opted to code the design patterns in a different programming language. Since the book's examples were in Java, I chose Python as the obvious choice for me.

It took me three days to make the Abstract Factory pattern work.

But let me assure you, after that intensive exercise, I truly understood how to implement the abstract factory pattern. As a fun side note, I also became well-versed in modeling a pizza franchise business! 😆

The key takeaway here is that learning complex concepts and embedding them in your memory takes time and effort. We might be able to develop simple skills without constantly referring to guides, thanks to trial and error and the valuable insights provided by StackOverflow. But for profound understanding and long-term retention, patience and repetition are essential.

Learning one thing at a time

As software developers, we reside in an industry that incessantly evolves, forcing us to adapt and acquire a broad range of skills. I love learning new things and experiencing that invigorating feeling when reading a paragraph that resonates with me. However, I must admit that what I find captivating today may be forgotten tomorrow.

That's why I recommend, not only to others but to myself as wellthe one who often needs the reminder the mostto focus on learning one thing at a time. Dedicate a week to mastering a small, specific concept, such as Data Transfer Objects (DTOs) in Java. Once you've learned this concept, consider writing an article about it. Feel free to visit the article whenever you have doubts or need a refresher.

For more complex subjects, like a cloud certification, break it down into manageable concepts. Let's say you plan to complete the certification within two months. Divide your time accordingly and dedicate each week to learning a specific service, following the provider's guide.

Read articles, engage in hands-on labs, write about your experiences, and repeat this process.

When you test your knowledge, rest assured that you'll have a solid understanding of the material.

Conclusion

In conclusion, writing enhances the learning process. This is not just a casual claim, but a fact. Let's recap the key points that illustrate the importance of technical writing for developers:

Traditional memorization-based learning methods fall short.
Profound understanding is crucial for effectively applying complex concepts.
Writing requires explaining, which reinforces understanding.
Passive learning (reading, watching) is not as effective as active learning (coding, writing).
Attempting tutorials in different programming languages or approaching the same problem from a different perspective increases comprehension.
We can revisit articles, but we can't revisit our fleeting thoughts.
Focus on learning one thing at a time for better retention.

If you've reached this point, I am honored by your commitment. Thank you for reading and considering the significance of technical writing for learning as a developer.

Reach out on Twitter to find more valuable content or just chat!

🐦 @victorgarciadev

😼 Github

References:

People remember 10%, 20%Oh Really?

Why Writing Helps You Learn

Victor Garcia Dev — Fri, 17 Sep 2021 13:40:01 +0000

Many of you may have tried to start technical writing and left it after a week.

Maybe someone has created a blog but stopped posting after a year or so.

You could have thought: "Why would I spent time writing for free if I don't like it so much. I should see another YT tutorial about this random topic"

Maybe you have wondered: "Would I be the one that replies in StackOverflow one day?"

Some of you may feel identified by these sentences. I will try to explain to you my main motivation to start writing:

Writing makes me learn better!

Traditional learning methods SUCKS!

As someone that comes from college here in Spain, I had to learn tons of things in a small amount of time. When the tests came, I could find myself with 8 exams in 4 days. This is Telecommunications Engineering we are talking about. Not an easy thing.

What would I do? What I have been educated for: Try to learn how to do some exercises from previous years. Memorize the parts that are always asked the same way.

It worked for 4 years!

When I arrived at my Machine Learning master's, I had to change. The math was the most complex I have seen in my life. Thanks to an awesome set of teachers, I STARTED to focus on understanding things in depth. The knowledge I have acquired during that year is one of the most durable I can account for.

Here is when everything started to make sense.

Overcome the "Tutorial Syndrome"

We are born in the Youtube era. We have seen an incredible amount of videos for many topics to find a solution. A lot of content creators, almost infinite knowledge at hand ... But let me ask you a question:

How much of this content did you remember after 3 days?

I will love to have some feedback in the comments. For me, almost nothing. Don't get me wrong. I love YT and it has brought amazing content to our lives for free.

But watching videos, reading books, posts ... IT'S ALL PASSIVE!

It requires a lot less attention than coding, for example. In my experience, I could think of a couple of concepts extracted from books. I was amazed by the information. It released all the dopamine it could.

Most of the time, every highlight in a book is forgotten. Lines of CODE and TEXT, created with BLOOD and SWEAT, usually aren't.

Increase understanding of topics

If you could name a topic that writing didn't help you to understand better, I am a living lie.

Here I will use an example of my own experience. I was reading "Head First Design Patterns". Recommendable by the way. In this book, one or more Design Patterns are introduced and explained in each chapter. I was reading it almost every day, but after a week I thought: "Okay, I did not remember any pattern. I don't know how to apply them"

So I decided: "Let's code them in a different language". Book examples were in Java, so for me, the obvious pick was Python.

IT TOOK ME 3 DAYS to make the Abstract Factory work! 😅

Don't have any doubt about this: I freaking know how to implement the abstract factory after that. And also learn how to model a pizza franchise business 😆

What I want you to see with this is: Learning things that perdure in your memory takes time! Probably, the complex things that you can do without checking a guide are built on multiple failed attempts and StackOverflow questions.

I will show you a graphic about the retention of information based on the channel it is acquired after 2 weeks.

Learning one thing at a time

As software developers, we live in an industry that is constantly evolving. We are required to manage a lot of tools. This urges us to learn a lot of different things. For so much time we lose focus.

I love to learn new things. I love that sensation of reading a paragraph and say: "My god, this is great to know". Does Victor remember next month? Of course not.

I recommend everyone, including myself (the one that needs it the most): One thing at a time. Let's spend a week learning a small concept, let say: DTOs in Java. If we learn them for a week, write an article about it. You could visit it if you have any doubts!

If you plan to learn something more complex, divide it and make it easier. A cloud certification for example. Let's say we plan to make it in 2 months.

Divide it into concepts by the guides of the provider and learn a service per week or so.
Read articles
Make labs
Write about the labs
Repeat

When you make the sample tests, I am sure you will understand everything.

PD: Skin in the game. I will try to do this for my next cloud certs.

Summary

Writing improves learning. This is FEKTS. The main points explain to defend this have been:

Traditional methods for learning with memorization do not work
Complex concepts need deep understanding to be used
Writing requires explaining. Explaining requires understanding
Passive learning (Reading, Watching) vs Active learning (Coding, Writing)
Try to code the tutorial in a different programming language. Or model the same problem differently for the same one
An article can be revisited. A thought can't
Learning one thing at a time

I am HONOURED if you have reached this point. Thanks a lot for reading 💙

Hopefully, I was able to illustrate how technical writing is important for learning as developers.

Reach out on Twitter to find more valuable content or just chatting!

🐦 @victorgarciadev

😼 https://github.com/victorgrubio

References:

People remember 10%, 20%…Oh Really?

Thanks and Keep It Up! 🦾🦾