Coley Woyak

Project overview

A recurring challenge for technical writers is figuring out how much information to include in end-user documentation. Which users will use this content? How much detail do they need to succeed? Are there specific features of the product that are confusing and require more depth?

This sample discusses environment variables on this platform. It was complicated to refine the content on environment variables because of how the platform organizes and stores these variables. Users could create global and project-specific variables. Unfortunately, the UI was almost identical for both types, making it unclear whether users were creating their variables at the global or project level. This necessitated more detail than would normally be required for an otherwise-straightforward concept.

Docs-as-code toolchain

We used a docs-as-code toolchain to create these tutorials and all other technical, user, and developer documentation, specifically:

• Asciidoc [lightweight markup language]
• Antora [static-site generator]
• Netlify [hosting]

On this page

There are two distinct sections in this sample: explanation and tutorials.

I modeled these sections on the Diátaxis Documentation Framework, which suggests organizing content by how it will be used instead of by reader persona. The explanation section explains how the platform uses and stores environment variables. The tutorials section walks a new user through creating environment variables one step at a time.

Environment variables

Environment variables are dynamic-named values that can be referenced inside of jobs.

Redacted uses two types of environment variables:

• Global: available for all projects on the platform
• Project: available only for the project in which it is created

NOTE: Environment variables are not shared between platforms.

Name

Names are always required. There are some restrictions when naming environment variables:

• The name of your variable cannot exceed 255 characters.
• The name can only contain:
• uppercase letters (A-Z)
• lowercase letters (a-z)
• numbers (0-9)
• underscores (_)
• hyphens (-)
• periods (.)

Description

Descriptions are optional. There are no restrictions on descriptions, though it's good practice to keep them short and informative.

Global variables

Access all global environment variables for the platform from the library page (link removed).

1. Verify your location to make sure you're accessing global environment variables.
• You should see the data management menu for all projects.
• Environment variables should be in the only options in the settings menu.
2. Additionally, you can use the breadcrumbs to verify your location. When working with global environment variables, you should only see the breadcrumb Projects.
3. In the top bar, you'll see when the list of variables was last updated, as well as a button to create a new global variable.
4. Search for global environment variables by name only.
5. The list of global environment variables includes the name and description of the variable, as well as a icon you can select to copy the variable. There is also a badge indicating that each variable is global.

NOTE: On the global environment variables menu, you can only view global environment variables. You can also create and edit them.

Project variables

Access your project's environment variables from the overview page (link removed).

You can create environment variables inside of a project. These will only be accessible within that project; other projects will not be able to access them.

1. Verify your location to make sure you're accessing project environment variables.
• You should see links to jobs, pipelines, and apps in the data management menu.
• In settings menu, you'll see environment variables and Docker credentials.
2. Additionally, you can use the breadcrumbs to verify your location. When working with project environment variables, you should see Projects followed by your project.
3. In the top bar, you'll see:
• when the list of variables was last updated,
• access to the project settings, and
• a button to create a new project variable.
4. Search for project environment variables by name only.
5. The list of environment variables inside of the project includes the name and description of the variable, as well as a icon you can select to copy the variable. There is also a badge indicating whether the variable is global or project.

You can view both global and project environment variables within a project, but you can only create or edit project variables.
There is also the option to override global environment variables within a project.

View and edit variables

To view the details for an environment variable, select it. Doing so will open a panel with the variable's details.

This is where you can edit a variable's name, description, and value.

IMPORTANT: You can only edit global variables from the project library page, and you can only edit project variables from the project overview page.

When you open the details for a global variable from the project environment variables list, you will see the option to override the variable for the current project only.

Tutorial 1: Create a project variable

Let's create the project environment variable $SCRANTON_PW, where we'll store the password for the Scranton Branch, scranton-paper.

ASSUMPTIONS: Let's assume that you've created the project Dunder Mifflin Paper Sales, and you have the right to create project environment variables.

Navigate to project environment variables

Access project environment variables from within your project.

1. Go to the Projects module from the primary navigation menu.
2. Go to the Dunder Mifflin Paper Sales project.

3. Use the breadcrumbs to confirm that you are in your project. In the image, the breadcrumbs read Projects / Dunder Mifflin Paper Sales.
4. Go to Environment variables from the secondary navigation menu. Notice that both global and project environment variables appear on this list.
5. Select the New variable button.

Create your variable

1. A panel will appear to create your variable.
2. Enter the name of your variable: SCRANTON_PW. Note the project label near scope.
3. Enter a description of your variable: Project password for the Scranton Branch.
4. Since this is a password, select the is password checkbox.
5. In the value field, enter the password: scranton-paper
6. Select the Save button.

Your project environment variable is now ready for use within your project.

Tutorial 2: Create a global variable

Let's create the global environment variable $DUNDER_PW, where we'll store the global password, dunder-mifflin.

ASSUMPTIONS: Let's assume that you are on a platform where you have the right to create global environment variables.

Navigate to global environment variables

You access global environment variables from the projects library page. Only global environment variables appear on this list.

1. Go to the Projects module from the primary navigation menu.
2. Verify that the breadcrumbs only contain Projects.
3. Go to Environment variables from the secondary navigation menu.
4. Select the New variable button.

Create your variable

1. A panel will appear to create your variable.
2. Enter the name of your variable: DUNDER_PW. Note the global label near value.
3. Enter a description of your variable: Global password for Dunder Mifflin Paper Company, Inc.
4. Since this is a password, select the is password checkbox.
5. In the value field, enter the password: dunder-mifflin
6. Select the Save button.

Your global environment variable can now be used by all projects on this platform.

• Back to overview
• Home

© Coley Woyak. All rights reserved.
Original design: Paradigm Shift by HTML5 UP & customized by yours truly.