Forem: Njong Emy

Starting Out with Technical Writing

Njong Emy — Tue, 01 Aug 2023 09:55:26 +0000

Introduction

Technical writing, just like many other fields, has been around for quite some time. But many people either don't know what it is or how to start. I get a lot of questions on how to begin and Matej recently asked me this question on Twitter. I hope this article addresses any questions anyone might have.

What is Technical Writing?

Before we dive into the subject, let's see what the term means in general.

There are a lot of definitions for technical writing. Some people think of it as the process of curating user guides for both hardware and software material, or project documentation. A great definition is one that defines the term as the process of writing or a writing discipline that involves splitting down complex concepts into much easier blocks so that others can understand.

Everyone can write, but as a technical writer, it's important that your writing comes across as easy and digestible to your audience.

What do you need to know?

As much as I encourage everyone to take the lead and start writing, there are a few things that you should know if you want your writing to stand out.

Research skills

No one knows everything. There is hardly ever one way to approach something, and even if we know much, we fall short most of the time. That's why it's important to have research skills. Some of what you write will most likely be material that you've gathered during research.

Writing skills

Don't be alarmed. I'm not asking you to be an expert.

To come off as a professional and organized writer, your grammar, vocabulary, and editing skills have to be good. We are surrounded by awesome pieces of software that help us polish our work without much effort on our side. Tools like Hemingway Editor, Grammarly, and many others have made it easy to write clear and organized material.

But remember, it's up to you as a writer to put out your ideas as best as you can. These tools won't do that for you.

Sufficient understanding of a concept

Writers who have paid gigs will attest that the topics they have to write about sometimes are topics they almost have no clue about. This is where the research skills come in again. Along the way, we have to learn bits of new technology and give ourselves time to understand new things.

If you have a sufficient understanding of a concept, all you need is research to add volume to what you already know. Nothing is too small to write about. If it helped you, then it can help somebody else.

Why should you write anyways?

Many people don't see the benefits of technical writing. It's way better when someone else writes about the solution to a bug you have, isn't it?

Learn double and help others

To write, you research. As you research, you learn. You're not only adding knowledge to yourself, you're adding it to whoever is going to read that article.

If you fix a problem in your code and decide to write about it, that same article could be a reference when you come across that problem in the future. It's like having notes.

Opportunities

People are looking for writers every day. An article I published here on Hashnode got me one of my best writing gigs, and all I had to do was write it. Put yourself out there and you will be shocked at the opportunities that come knocking at your door.

$$

Being financially independent is a huge reason to start honing your writing skills. You get paid to learn something new and write about it. Price ranges differ, and are based on the company or person hiring you, or how much experience you have. What you should know, is that some companies are ready to really invest in someone who can write guides, tutorials, and documentation for their products.

Starter Steps

Now that you've seen how amazing the perks are, let's see how to start from zero.

Free courses

To start any craft, you need a head start. How can I make the best out of my writing? How do I manage my tone? How do I use headings? Fortunately, Google has a free course that can help. It gives a general idea of what technical writing is, and provides other helpful resources. You can check it out here.

Free platforms

You can start practicing your skills anywhere. As in an empty MS word document or any text editor of your choice. When you're ready to start publishing your work online, there are also platforms that can help you do so. Hashnode is a very great example! It has a lot of fun perks and a thriving community. There are other online platforms such as dev.to and Medium. Each of these has advantages particular to it. If you can't decide, you can cross-post!

Now that you've taken the course (assuming you took it), how would you approach your first article? Normally, the course should have highlights to help you tackle this. The following steps are listed according to how I approach my articles.

Have a title?

Do you have something in mind? Make it catchy. Assuming you were a random user and saw an article with the topic you chose. Would you click on it? Make the title short.

Know your audience

Are you writing starter guides? Then your audience will most probably be beginners in that technology. Write first for the audience, and then for yourself. If you are an expert in React, you might be tempted to use advanced terminology in an article that is targeted at beginners. Have the audience in mind as you write.

Beginners writing for other beginners usually turns out well because they use terms and concepts that they and the intended audience will understand.

Create an Outline

I give myself too much credit sometimes, and just think that words will flow when I start writing. Unfortunately, this leads to writer's block almost all of the time. An outline gives you a clear understanding of how your article should be structured and what you need to put your research time into. When you know what you have to write, you're going to write it.

DYOR (Do Your Own Research)

A very important step. Find out what you don't know in relation to your topic, and learn new things as you go. The research will make up a great part of your writing, and you are assured that you know what you're talking about.

Let the writing begin...

With the awesome platforms, the helpful tools, and the excited writer that you are, you're on your way to being a superhero (writer).

Edit

As awesome as the above tools are, they aren't perfect. They won't catch every single fault, and proofreading is your best friend at this stage. Read over your work again, and again. Read it out loud. Have your friend read it. You'll see that some things should've been rephrased and some words needed to go!

Publish

This step is self-explanatory :) Let the world see your work!

Conclusion

Practice makes improvement. Write as much as you need to get comfortable. Don't be afraid to take opportunities when they come. And if you feel like you're ready, start looking for writing jobs on LinkedIn, or on freelance platforms like Upwork.

How to Store Images in MongoDB using Cloudinary: MERN Stack

Njong Emy — Thu, 27 Jul 2023 08:10:22 +0000

As a new developer trying to climb your way through practice projects, you can only build so many to-do list apps. Things are going to get harder as you build more apps, and you need to be ready for it. Nowadays, apps deal with a lot of media. Whether it be user profile images, videos, audio, or GIFs. As a developer, you need a place to store these images.

But where?

If you said database, you might be a little wrong. Storing images directly in your database is not only a complex process (I say complex because I looked into the option, and it definitely didn't look like ABC to me), but it also comes with performance and security issues.

A better solution for this is the cloud. Enter Cloudinary.

In simple terms, Cloudinary is a SaaS (Software as a Service) that enables users to upload, manage, and deliver media for their apps and websites. You upload your media to Cloudinary, and then you get to use that media in your app through a CDN (Content Delivery Network) that Cloudinary provides.

What are we building exactly?

In this article, I'll show you how to build a small app that accepts images through a form, sends the image to Cloudinary, stores the image's CDN link in our MongoDB database, and then retrieves the image back in the front end.

I promise that it's not as complicated as I might have made it sound.

This is what our final app is going to look like;

If you look closely at the console, you see an image object with two properties, a publicId and a url. This is the response gotten after submitting our form with an image to the backend.

Prerequisites

To be able to follow through the steps with ease, you'll need a basic understanding of the core technologies in the MERN stack;

MongoDB
Express.js
React.js
Node.js

Don't worry if you're not an expert (God knows I'm not), because I'll be showing you how most things work at each step.

To spice our styling up a little, I'll be using TailwindCSS. It's okay if you're not a fan of it. We still accept you.

The Backend

Our starting point is the backend. To initialize this project let's create a directory called my-fave-project. If you're coding among friends and must absolutely look cool, then open up your terminal/command prompt and run the following commands to easily do this;



cd <the directory in your computer where you want to create the folder>
mkdir my-fave-project
cd my-fave-project
mkdir my-profile
cd my-profile

When typing out the first line, make sure that you specify the folder in your computer where you want the project to be. I created mine in the Desktop directory. The fourth line creates the my-profile folder, and the fifth line lets us navigate into it. Another way is to create the my-profile folder directly from your IDE when creating a new project.

Inside my-profile, you want to create another folder called backend. Later on, we'll create a frontend folder so that the two are under the same project, but live in distinct folders for clarity.

So go ahead and hit mkdir backend and then cd backend. You can now open this folder up in your IDE of choice.

Now that we're in the backend folder, we'll need to install dependencies. Tiny little libraries and components that our app will need in order to work. Before that, go ahead and run npm init -y to create a package.json file.

As for dependencies, we're going to need;

cloudinary: For us to be able to use functions from Cloudinary, we'll need this package.
cors: Cross-Origin Resource Sharing errors will arise because we are serving the frontend and backend from different domains. We need the frontend to access backend resources served outside of it's domain, and this package will enable us create a middleware bypasses cors issues.
dotenv: We're going to be dealing with environment variables, and this package helps us use these variables with process.env.
mongoose: This library makes working with MongoDB and Nodejs easier.
nodemon: Whenever we make changes in our code, it's just convenient that our server automatically restarts.
express: This small backend framework is what will help us easily build the APIs that we need.

It is worth noting that most of the aforementioned packages can also be installed with Yarn, if that is your package manager of choice.

The Server

Now that we have our dependencies out of the way, we can go ahead and spin up our express server.

In the root of your backend folder, create a server.js and a .env file. Inside the .env file, add PORT = 5000 as the only line in it for now. Our server will be hosted on this port.

Now, in the server.js file, our first three lines would be to import the necessary frameworks and packages we need to start the server;



require("dotenv").config()

const express = require('express')
const cors = require('cors')

We can now initialize the app, and bring in middleware;



//initialize the app
const app = express()

//middleware
app.use(cors())
app.use(express.json())
app.use((req, res, next) => {
    console.log(req.path, req.method)
    next()
})

As I explained before, we need cors to handle any Cross-Origin Resource Sharing errors we may come across. The second middleware is used to parse JSON requests, and the third middleware will enable us to see any request that is being sent to the server in our console. These requests are usually of the form /user POST for example, where we have the request path and the request method that were sent.

After all these initializations, we can listen for requests;



//listen for requests
app.listen(process.env.PORT, () => {
    console.log(`Server is running on port ${process.env.PORT}`)
})

Notice how we used the process.env.PORT to reference the port number we specified in our .env file.

To see if the server is running, type nodemon server in your console and hit enter.

You should see a "Server is running on port 5000" in your console if everything is working fine.

The Database

We're going to be using MongoDB for this article, and since I already assume basic knowledge, we're not going to go into the depths of what it is. Collections, documents, models, schemas, etc are some of the terminologies we'll encounter in this section. If you have trouble understanding what they are, I suggest you do a little bit of reading before you continue.

Let's create a new project and database in our Mongodb cloud and name it My-profile. Take note of your username and password, because we'll need it for the connection string.

To now connect our Node.js backend to the database, create a new folder in the root of the project and name it config. Inside config, create a new file, db.js.

Inside it, paste the following code;



const mongoose = require('mongoose')

const connectDB = async() => {
    try{
        const conn = await mongoose.connect(process.env.MONGO_URI, {
            useNewUrlParser: true,
            useUnifiedTopology: true
        })

        console.log(`MongoDB connected: ${conn.connection.host}`)
    } catch (error) {
        console.error(`Error: ${error.message}`)
        process.exit(1)
    }
}

module.exports = connectDB

The connectDB function above uses the connection string, which we have provided as an environment variable, to connect to our MongoDB database. It logs a success message if the connection is successful, and an error message if otherwise.

In your .env file, let's create a new variable, MONGO_URI;



PORT = 5000
MONGO_URI = mongodb+srv://<username>:<password>@cluster0.vaf008n.mongodb.net/?retryWrites=true&w=majority

Make sure to replace username and password with your own values.

Go back to your server.js file, and import the connectDB function. Right before you create the express app, call the function. Our final server.js file with our server running in the console, and our connected database will finally look like this;

The Schema

Now that we have connections done, let's start building up the structure of our application. Schemas tell us about the structure of the data that is stored in our database. We apply the schema to a model so that we can perform certain functions on it.

For this app, our schema will be nothing complicated. We only need three objects to store the user's name, username, and data for the image.

In the root of our project directory, let's create a folder called models, and inside of it, a file, userModel.js;



const mongoose = require('mongoose')

const Schema = mongoose.Schema
const userSchema = new Schema(
    {
        name: {
            type: String,
            required: true,
        }, 
        username: {
            type: String,
            required: true,
        },
        image:{
            publicId:{
                type: String,
                required: true,
            },
            url: {
                type: String,
                required: true,
            }
        }
    }, {timestamps: true}
)
module.exports = mongoose.model('User', userSchema)

The very first line imports mongoose because we'll need it to create the schema. The schema variable defined on the second line creates a reference to the Schema class which exists in mongoose. To create a schema, we make use of the schema constructor, which takes an object as its argument. It is inside this object that we will define the structure of the data we want to store in our database.

We have the user's name which is a string, their username, and the image object. The image object takes in two properties; the publicId and the url, which are provided to us by Cloudinary. Our main focus is the url, because it is what we can eventually use in our frontend to get the image.

Before we jump into creating the controller, let's handle our Cloudinary functions first.

Cloudinary

Head over to cloudinary.com and create an account, or login if you've visited before. You're ported over to a Getting Started page, where you are provided with configurations for different SDKs. Under the Node.js SDK, copy the cloud name, API secret, and key.

Back in our IDE, let's create a new folder called services, and then a cloudinary.js file in it. This is where we will create the function that uploads the image sent through the form to Cloudinary.

We begin by importing the cloudinary package we installed, and then providing our configuration details;



const cloudinary = require("cloudinary").v2

cloudinary.config({
    cloud_name: process.env.CLOUD_NAME,
    api_key: process.env.API_KEY,
    api_secret: process.env.API_SECRET
})

Don't forget to actually create these environment variables in your .env file. Beneath the config, we can now create our upload function;



const uploadToCloudinary = async (path, folder = "my-profile") => {
  try {
    const data = await cloudinary.uploader.upload(path, { folder: folder });
    return { url: data.secure_url, publicId: data.public_id };
  } catch (err) {
    console.log(err);
    throw err;
  }
};
module.exports = { uploadToCloudinary}

All the function above does, is uploads the image it receives from the frontend to Cloudinary (specifically to the my-profile folder, so that the images stay in one place) through the cloudinary.uploader.upload() method, and then returns a secure_url (a CDN link to that image), and a public_id. We export the function at the end so that we can use it in another file.

And that's it for the Cloudinary part.

The Controller

So far, we've created and run our server, handled the schema, and created a function that uploads an image to Cloudinary. We now need to create functions that will run whenever we make requests. In other words, we need to create methods for our model.

Since we are already in the spirit of splitting our app into folders for clarity, create another folder called controllers, and then a userController.js in it.

Our controller will only have one function, which handles the request that creates and stores the user in the database.

In our userController, we start by importing necessary packages and functions. We're going to need our model and the Cloudinary function we created before.



const User = require('../models/userModel')
const { uploadToCloudinary } = require('../services/cloudinary')

As for our function,



const createUser = async (req, res) => {
    const {name, username, image} = req.body
    try{
        let imageData = {}
        if(image){
            const results = await uploadToCloudinary(image, "my-profile")
            imageData = results
        }
        const user = await User.create({
            name,
            username,
            image: imageData
        })

        res.status(200).json(user)
    } catch(e) {
        res.status(500).json({error: "A server error occurred with this request"})
    }
}

module.exports = { createUser }

The function receives the user's name, username, and image through the request body. We start by creating an empty object in which we will store the data we get back from Cloudinary. If the image was truly sent from the frontend, we call the upload function that we imported and pass in the image to it. We know that we'll get back the url and publicId from Cloudinary after the image is uploaded, so we store that returned result in the imageData object that we created.

After that function is run, we can now create the user document and send the name, username, and image (since imageData has the data for our image, we send it as the value for our image field). Our server sends a 200 status code response if the request is successful, and a server error if something obstructed the request.

Let's export that function because we'll need it for our routes. So our controller file looks like this overall;

The Route

This is the last step of our backend setup. With routes, we'll be able to send requests from our frontend to our backend.

You already know the drill. Create a routes folder, and then a user.js file inside of it.



const express = require("express")

//controller functions
const { createUser } = require('../controllers/userController')

const router = express.Router()

//create user route
router.post('/', createUser)

module.exports = router

Our router isn't much. express.Router() creates a new router object which we'll use to define our routes. The only route we need is to create the user, and this is obviously a POST request, hence the post method.

After exporting the router, let's head back into our server.js and import our route.



require("dotenv").config()

const express = require('express')
const cors = require('cors')
const connectDB = require('./config/db')
const userRoute = require('./routes/user')

//initialize the app
connectDB()
const app = express()

//middleware
app.use(cors())
app.use(express.json())
app.use((req, res, next) => {
    console.log(req.path, req.method)
    next()
})

//routes
app.use('/api/user', userRoute)

//listen for requests
app.listen(process.env.PORT, () => {
    console.log(`Server is running on port ${process.env.PORT}`)
})

You can see that we imported the route at the top of the file. When a request is made to the /api/user route, the app.use method will execute the userRoute router object, and the controller linked to this router object handles the request and sends a response.

That's about it for our backend! Let's jump into the client side of things now.

The Client

Since all of our server side is concealed in the backend folder we created at the start, let's create a frontend folder to house our client side.

We'll only need to install React and TailwindCSS. Don't forget to leave from the backend folder to the frontend folder.

To install React first with Vite, we use the command npm create vite@latest . -- --template react to install the library in the directory we are in. The console then prompts us to run npm install and npm run dev to create our node_modules folder and start the server respectively.

To install Tailwind, the docs provide us with the necessary steps.

Feel free to clear the boilerplate of anything you don't want. This is what my file tree looks like after removing unnecessary files.

You can quickly test if Tailwind works by creating a p tag in your App.jsx and giving it some text and color.

We can now dive into our code now. Let's create a pages folder inside src, and create two files in it, Form.jsx and Profile.jsx. Make sure to import the Form.jsx file in your App.jsx because it's the page we want to see when the app first loads.

To make things easier and faster for me, I decided to use a TailwindCSS component library called HyperUI. It provides free open-source components that you can copy into your project and edit according to your needs. If you don't want to use a component library, feel free to build your components from scratch. This is just a step to make things go faster.

Let's copy a form component from HyperUI, and edit it to make it work for us. If you use one of their form components, make sure to install the TailwindCSS forms plugin.



import { useState } from "react"

const Form = () => {
    const [name, setName] = useState("")
    const [username, setUsername] = useState("")

  return (

  <div className="mx-auto max-w-screen-xl px-4 py-16 sm:px-6 lg:px-8">
    <div className="mx-auto max-w-lg text-center">
        <h1 className="text-2xl font-bold sm:text-3xl">Hello there!</h1>

        <p className="mt-4 text-gray-500">
        Please provide your name, username, and profile image
        </p>
    </div>

    <form action="" className="mx-auto mb-0 mt-8 max-w-md space-y-4">
        <div>
            <label for="name" >Name</label>

            <div className="relative">
                <input
                type="text"
                className="w-full rounded-lg border-gray-200 p-4 pe-12 text-sm shadow-sm"
                placeholder="Enter your name"
                value={name}
                onChange={(e) => setName(e.target.value)}
                />               
            </div>
          </div>

          <div>
                <label for="username" >Username</label>

                <div className="relative">
                    <input
                    type="text"
                    className="w-full rounded-lg border-gray-200 p-4 pe-12 text-sm shadow-sm"
                    placeholder="Enter username"
                    value={username}
                    onChange={(e) => setUsername(e.target.value)}
                    />

                </div>
           </div>

           <div>
                <label
                    htmlFor="profile_image"
                    className="block font-medium text-deepgray"
                >
                    Upload image
                </label>

                <input
                    name="image"
                    className="w-full rounded-lg border-gray-200 p-3 text-sm"
                    placeholder="Image"
                    type="file"
                    accept="image/*"
                    id="image"
                    onChange={handleImage}
                />
            </div>

            <div className="flex items-center justify-between">
                <button
                    type="submit"
                    className="inline-block rounded-lg bg-blue-500 px-5 py-3 text-sm font-medium text-white"
                >
                    Submit
                </button>
            </div>
        </form>
    </div>
  )
}

export default Form

In the component above, we have three input fields for the user's name, username, and their image. We use the useState hook to collect the input values for the name and username. For the image, we'll do something slightly different.

This is how our form looks like on the browser by the way;

Now, let's handle the image input and create the handleImage function.

Create two new states in addition to the ones we have, and then add the following functions;



    const [image, setImage] = useState(null);
    const [imageBase64, setImageBase64] = useState("");

    // convert image file to base64
    const setFileToBase64 = (file) => {
    const reader = new FileReader();
    reader.readAsDataURL(file);
    reader.onloadend = () => {
      setImageBase64(reader.result);
    };
  };

  // receive file from form
    const handleImage = (e) => {
    const file = e.target.files[0];
    setImage(file);
    setFileToBase64(file);
  };

The handleImage function is what receives or collects the image that is entered in the form. It then runs the setFileToBase64 function, to convert the image to base 64. You can read up about pros and cons of converting images to base 64, but note that there are obviously other ways to handle images in forms.

The POST Request

Now that we are done collecting the necessary inputs from our form, let's send our first request to the backend. We need a function that sends a POST request when we click our submit button.

Let's create two more states, data and Loading;



const [loading, setLoading] = useState(false);
const [data, setData] = useState(null);

The first state will handle our loading states so that we don't leave users hanging when they send a request. The second state will store whatever data we send to the database.

As for the handleSubmit function,



const handleSubmit = async (e) => {
    e.preventDefault()
    setLoading(true)
    const response = await fetch("http://localhost:5000/api/user", {
        method: "POST",
        headers: {
            "Content-Type": "application/json"
        },
        body: JSON.stringify({name, username, image: imageBase64})
    })

    const json = await response.json()

    if(response.ok){
        setLoading(false)
        setData(json)
        console.log(json)
    }
  }

Don't forget to call the function in the opening form tag with the onSubmit event handler.

If you try to fill out the form and send it, you might get a response in your frontend, and you can see the image in your Cloudinary dashboard if you navigate to your folders;

If you take a look at your MongoDB, you'll also notice a new document in the database you created! You can see the image URL stored in our database too. If you paste the link in an empty tab, it opens the image directly.

The End

And that's it for all the magic we've been performing in this article. There is still so much you can do to enhance the solution we've implemented. But after this step, I hope it won't be so hard to grab the images you've stored in your backend and use them to your liking.

I had so many difficulties dealing with a similar problem before, so I thought writing an article could help anyone else figure their own bugs out. As a final note, I hope this breakdown is clear and easy enough to follow, and I can't wait to hear any other opinions you may have in the comments.

Peace out.