Tech 101 for Technical Writers

A brief overview of words/concepts your SMEs use and expect you to know.

This post is intended to simply describe technical words/concepts that frequently come up when talking with engineers and product managers.

Note: This is non-comprehensive. The definitions are very high-level to remain approachable.

A

Agile

A project philosophy based on breaking large projects into smaller, more manageable tasks, and integrating continuous delivery and improvement in everyday work.

You may hear this contrasted with “waterfall” project management. “Waterfall” projects are done in phases, with extensive planning for all the stages of work and longer turnaround times. Both philosophies are valid.

Algorithm

Instructions to perform a task. In software, this usually describes code behavior.

API

Acronym for “Application Programming Interface”. In this context, a “programming interface” is a way for other people to build with the application. This is typically done through endpoints (URLs other developers access to get or send data.)

Google Maps is a great example. Let’s say a developer wants to build an air quality map widget for a website. Google Maps offers an Air Quality API, so the developer can use Google’s data to build their widget.

App

Short for “application”. An application can be any piece of code.

B

Backend

Refers to code the user doesn’t see. “Backend” code processes data and runs business logic, which is then sent to the “frontend”, or the code the user interacts with.

Bash

A program available on most computers that allows the user to interact with their data from the terminal. Read more about bash here.

Bit

The smallest form of data in computing. A “bit” can have a value of 0 or 1.

Branch

Frequently used in docs-as-code infrastructure. When working on code, you shouldn’t directly make changes to the work that users interact with. Instead, you should make a “branch” of the original code.

A branch is a copy of the project where you can write and test new work. When you’re confident your change is ready, you can then merge your work with the main project again.

Build

Build can be a noun or a verb. When used as a noun, “build” describes the environmental variables and configurations used to compile code. When used as a verb, “build” describes the act of compiling code.

Byte

A “byte” is a very small piece of data, made up of bits. Data is broken up into chunks so hardware can interact with it. These chunks are called “bytes”.

C

Cloud

Refers to the machines running/storing/saving data not hosted on your computer.

Command line

Another word for the “terminal” in a computer.

Command line interface (CLI)

Refers to ways a user can interact with the command line/terminal through text.

Command prompt

Each command line interface has a command “prompt”. This is the symbol that indicates the beginning of the line. Common prompts include > , % , $ , and - . The symbol depends on the OS, the command line interface, and customized options from the user.

Compile

Any code written by a human must be translated into bits so the computer hardware can understand the code’s instructions. When a human translates the code into bits, they “compile” it. This can also include adding images, installing dependencies, and other necessary steps to making the code run.

Container

A packaged piece of code that includes all the necessary information to run an application. Think of these like a DIY kit. It has all the materials necessary to do a task, and now you can focus on the task itself.

Cron

Frequently used in the context of “cron jobs”. A scheduling application that runs tasks at certain times and frequencies in the background of your computer.

D

Deployment

In software, “deployment” means making packaged software usable to others. By deploying software, code must be compiled or built and is frequently sent to another platform so others can access it. In general, deployed software is considered “live”, or ready for users.

DevOps

Short for “development” and “operations”. DevOps is a software philosophy based around removing barriers between developers and operation practitioners (like system administrators, infrastructure engineers, and release managers.)

Since the early 2010s, it’s also expanded to include security and design. Documentation should be included in your definition of DevOps, and if it isn’t, I want to know why you like making things harder for yourself.

To read more about DevOps, check out this GitLab article.

Directory

Another word for “folder”. When you want to organize multiple files, you put them in a “directory”.

You may have written something like “Navigate to the project directory”, and included a code sample like this:

> cd /project-directory

In this case, project-directory is the directory name. The / before the name indicates it’s a directory.

E

Executable

Also frequently called an “executable file”. An “executable” is the machine-readable file created when a human compiles code.

F

Flag

A software flag is like an on/off switch. Flags represent conditions, like “Only run this code when the user is on a Mac” or “Do not run this code if the user denied accepting cookies”.

A common subset of flags is “feature flags”. Unlike code flags, a feature flag is like an “on/off” switch for an entire piece of code. These are useful for deployed code with active users, especially when testing new features you aren’t confident in.

Fork

If you practice docs-as-code, you may have “forked” a repository in the past. “Forking” means you make a copy of all the original code, and that copy lives separately from the original. GitHub has a great explanation in its “About forks” guide.

Frontend

Refers to the code the user sees. “Frontend” code typically takes data from the user and sends it to the “backend” code for processing. Frontend code can also make the data visually appealing.

G

git

A content management system for code.

H

Host

The computer that runs or stores data. If something “hosts” code, it stores it and runs it when required. If data is “hosted”, the data is not stored on your computer.

Hotfix

Refers to a solution for a code bug or security problem, quickly developed and pushed out. Hotfixes aren’t intended to be permanent fixes, but buy time while the team figures out what to do next. They’re like bandaids before you can get to a doctor.

HTTP(S)

Acronym for Hyper-Text Transfer Protocol (Secure).

HTTP Method

An “HTTP method” refers to how an API interacts with other services. The most common methods are “GET”, “POST”/”PUT”, “READ”, and “DELETE”.

Read more about HTTP methods in this ReadTheDocs guide.

I

Index

Index can be a noun or a verb. As a noun, “index” means the position of an item in an array. If you have a group of terms like:

• red
• orange
• yellow

Each term in that list is called an “item”. “Red” is first, “orange” is second, and “yellow” is third. Each item has a position (first, second, and third) and that position is called the item’s index.

Computers start counting at 0 though, so “red” is at index 0, “orange” is at index 1, and “yellow” is at index 2.

As a verb, “index” means to evaluate and organize data for future searching. This frequently includes adding tags or metadata. Documentation must be indexed for findability.

L

Localhost

Your computer.

P

Patch

Software that fixes a bug or security problem. Patches typically aren’t big enough to warrant version changes in software. These are released when bugs are discovered and must be fixed before a new version releases.

Path

Describes the location of a file. If a file filename.txtlives in a project directory project-directory, its path is project-directory/filename.txt .

R

ReadMe

A file describing the code. This may include instructions, dependencies, known bugs, FAQ, or anything else the user needs to know.

Repository

The code/project folder. A repository typically refers to git projects.

REST (or RESTful)

Describes an API behavioral architecture. Read more about REST in this RedHat article.

S

SaaS

Acronym for “Software-as-a-Service”. Check out IBM’s explanation here.

Script

A small piece of code, typically to automate a task.

SDK

Acronym for “Software Development Kit”. An SDK is typically a collection of resources (like documentation, editors, debuggers, etc.) provided to a developer to build software with.

SDLC

Acronym for “Software Development Life Cycle”. The SDLC is the process code goes through before it’s released.

Shell

A program available on most computers that allows the user to interact with their data from the terminal. Like “bash”.

SRE

Acronym for “Site Reliability Engineer(ing)”. Like DevOps, SRE’s goal is to produce scalable and reliable applications by encouraging developers to think about their code from an infrastructure perspective.

Subdirectory

Another way to say “folder inside a folder”. If you have a project directory project-directory , and inside that folder you have another directory called images , the images folder is a subdirectory.

T

Terminal

A screen that provides text-based commands and responses for hardware information. “Shell” and “bash” use the terminal to display information.

Toolchain

Another word for “tech stack”. A “toolchain” describes the products used to create an application/product.

Tunnel

A “tunnel” is a service that transfers network traffic before it reaches an application. A tunnel can also perform actions on the traffic, like analyzing, filtering, obscuring, sanitizing, etc.

To read more about tunnels, Cloudflare has a decent explanation here.

U

UML

Acronym for “Unified Modeling Language”. A standardized diagram system for engineers to describe their software’s structure and behavior.

W

Wizard

Another word for “guided tutorial”. A user-interface tool that guides a user through instructions.

I hope this was helpful! I’m happy to take feedback on the entries here. Feel free to add more terms and definitions in comments, too! I may add more as time goes on.

About the Author

Jess Schalz (she/they) is a software engineer-turned-technical writer. She has a terrible cat named Sudo, and the two of them live in Minneapolis, MN.