This is where automation comes in. By combining OpenAPI specifications with GitHub Actions, you can ensure your documentation is always in sync with your API changes.

• OpenAPI acts as the single reference point for your API design, keeping your docs consistent, accurate, and aligned with your API.

• GitHub Actions automates the workflow, validating your spec, building docs, and publishing to GitHub Pages in seconds.

This tutorial walks you through a working example of how to use GitHub Actions to auto-update your docs.

Table of Contents

• Prerequisites

• How to set up your repository

• How to Create the OpenAPI Specification

• How to Test the API Spec Locally

  • Install tools

  • Create a landing page

  • Validate Your Spec

  • Preview in the Browser

• How to Push Local Changes to GitHub

• How to Set Up Your GitHub Actions Workflow

• How to Set Up GitHub Pages

  • What is GitHub Pages?

  • Setting Up GitHub Pages

• How to Handle Multiple Versions

  • About the Versions

    • Version 1 (v1)

    • Version 2 (v2)

    • Version 3 (v3)

  • How to Set Up the Versions Locally

  • How to Validate the API Specs

  • How to Update the GitHub Actions Workflow

• Summary

Prerequisites

• Node.js and npm installed.

• A GitHub account with basic Git knowledge.

• Visual Studio Code Editor.

• Basic knowledge of documentation and OpenAPI.

How to Set Up Your Repository

If you don’t already have one, create a GitHub repository. For this tutorial, I’ll use api-docs as the repo name.

Then open VSCode and create a folder with the same name.

How to Create the OpenAPI Specification

Inside the folder you just created, create a folder called spec and add a file named greetings.yaml with the following content:

openapi: 3.0.3
info:
  title: Greetings API
  version: 1.0.0
  description: This is a greetings API demonstrating a simple greeting endpoint with query parameters and multilingual support.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.yourdomain.com/v1
    description: Production server(v1)
  - url: https://staging.yourdomain.com/v1
    description: Staging server(v1)
security:
  - api_key: []
paths:
  /hello:
    get:
      summary: Returns a greeting
      operationId: getGreeting
      parameters:
        - name: name
          in: query
          required: false
          description: Name of the person to greet
          schema:
            type: string
            example: Ezinne
        - name: lang
          in: query
          required: false
          description: Language of the greeting (default is English)
          schema:
            type: string
            enum: [en, fr, es, ig]
            example: en
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                english:
                  value: { message: "Hello, Ezinne!" }
                french:
                  value: { message: "Bonjour, Ezinne!" }
                spanish:
                  value: { message: "¡Hola, Ezinne!" }
                igbo:
                  value: { message: "Ndeewo, Ezinne!" }
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header

This is a simple spec with multilingual greetings. As your API grows (say more languages or versions), keeping docs in sync manually might get tedious. That’s why automation helps.

How to Test the API Spec Locally

Install tools:

Before setting GitHub Actions, you can test the API Spec locally on your machine by setting up Redocly (used to be called Redoc) and testing it in an HTML environment.

Redocly is a lightweight, customizable tool to render OpenAPI specs as an interactive HTML documentation. It’s ideal for static site deployment which makes it ideal for this scenario.

• Install Redoc globally with npm install -g @redocly/cli

• Install http-server globally with npm install -g http-server

The http-server is a local server you can use to test the doc on your machine before you push to GitHub and deploy to GitHub Pages.

Create a landing page:

In your project, make a docs folder and add index.html:

<!DOCTYPE html>
<html>
  <head>
    <title>API Documentation</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <redoc spec-url="../spec/greetings.yaml"></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
  </body>
</html>

Validate Your Spec:

redocly lint spec/greetings.yaml

You should see this if there are no errors or warnings:

Woohoo! Your API description is valid. 🎉

Note: Validating your API Spec before testing is important as it’ll flag any possible errors. This is because Redocly will fail to run the preview if there are any errors in your spec.

Preview in the browser:

Run http-server, and you should see this in the terminal:

Starting up http-server, serving ./
Available on:
  http://127.0.0.1:8080
  http://192.168.x.x:8080
Hit CTRL-C to stop the server

Open http://127.0.0.1:8080/ and navigate to /docs to see your docs.

How to Push Local Changes to GitHub

After making local changes, you need to set up the API documentation so it can update automatically whenever you make changes.

Run these commands if you are pushing to the repository for the first time:

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin <your-repo-url>
git push -u origin main

How to Set Up Your GitHub Actions Workflow

You can set up your GitHub workflow by creating a few folders.

First, create .github/workflows/ in the api-docs folder. Then, inside the workflows folder, create a docs.yml. This is the workflow file that will serve as a trigger to run validation, generate the HTML with Redocly, and deploy to GitHub Pages at the same time.

name: Build API Documentation and Deploy to GitHub Pages

on:
  push:
    branches:
      - main
    paths:
      - 'spec/greetings.yaml'

jobs:
  build-spec:
    runs-on: ubuntu-latest
    permissions:
      contents: write # needed for gh-pages deployment

    steps:
      # 1. Checkout repository
      - name: Checkout code
        uses: actions/checkout@v4

      # 2. Set up Node.js
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      # 3. Install Redocly CLI
      - name: Install Redocly CLI
        run: npm install -g @redocly/cli

      # 4. Validate OpenAPI spec
      - name: Validate OpenAPI Spec
        run: redocly lint spec/greetings.yaml

      # 5. Build output directory
      - name: Create build directory
        run: mkdir -p public

      # 6. Copy spec
      - name: Copy spec
        run: mkdir -p public/spec && cp spec/greetings.yaml public/spec/

      # 7. Copy landing page
      - name: Copy landing page
        run: cp docs/index.html public/index.html

      # 8. Deploy to GitHub Pages
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Here’s what’s going on in this code:

• Runs when changes are pushed to main that affect spec/greetings.yaml.

• Checks out the repo code.

• Sets up Node.js and installs Redocly.

• Validates your OpenAPI spec (so broken specs won’t deploy).

• Copies the spec and index page into a public/ folder.

• Deploys public/ to the gh-pages branch with GitHub Pages.

Since we’re done with local testing, update the file path in the index.html:

<!DOCTYPE html>
<html>
  <head>
    <title>API Documentation</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <redoc spec-url="./spec/greetings.yaml"></redoc> <!--update the filepath to match your gh config-->
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
  </body>
</html>

This is so the public directory in the workflow will be able to access it correctly.

This workflow will only run when it detects changes in the API Spec (greetings.yml). To see the workflow in action, make a minor edit in the greetings.yaml.

Push the changes to your GitHub repository:

git add .
git commit -m 'add changes'
git push

How to Set Up GitHub Pages

What is GitHub Pages?

GitHub Pages is a hosting platform owned by GitHub where you can host websites directly from your GitHub account. This means you can publish static sites on the internet using a GitHub domain and anyone with the website link can access it.

There are other hosting platforms you can use to deploy static websites such as Netlify and Vercel. But using GitHub Pages for this documentation is easier to set up as it’s on the same platform.

Setting up GitHub Pages

Set up GitHub Pages by clicking on the Settings tab in your repository.

Under Source, choose:

• Deploy from branch: gh-pages

• Folder: / (root)

Then save and wait for the workflow to finish.

Your docs will be live at: https://<username>.github.io/api-docs.

How to Handle Multiple Versions

What if you had multiple API versions to update? Let’s assume the simple greetings API in this tutorial had more features added to it across different versions. In this case, you can manage the APIs for the different versions in a single page and also build and deploy it automatically.

About the Versions

Version 1 (v1)

This is the starting point which is greetings.yaml. The API only has a single /hello endpoint that returns a greeting in four languages (English, French, Spanish, or Igbo).

Version 2 (v2)

In version 2, the API adds create and read features. You can:

• Use POST /hello to create and save a greeting.

• Retrieve greetings by their unique ID with GET /hello/{id}.

Version 3 (v3)

Version 3 builds on top of v2 by adding an update functionality. Along with creating and retrieving greetings, you can now update an existing greeting using PUT /hello/{id}.

How to Set Up the Versions Locally

First, create a v1 folder and move the greetings.yaml file to it. Since we are going to be using versions, you can delete the existing spec folder.

Then, create a v2 folder and create a greetings-v2.yaml file. Get the greetings API for version 2 here.

Next, create a v3 folder and add greetings-v3.yaml file. Get the greetings API for version 3 here.

To follow the same pattern with others, rename the version 1 file to greetings-v1.yaml. Then update your index.html to accommodate the other two versions.

<!DOCTYPE html>
<html>
  <head>
    <title>API Documentation</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
      body {
        font-family: Arial, sans-serif;
        margin: 0;
      }
      header {
        background: #2c3e50;
        color: white;
        padding: 1rem;
        display: flex;
        justify-content: space-between;
        align-items: center;
      }
      select {
        padding: 0.4rem;
        font-size: 1rem;
      }
    </style>
  </head>
  <body>
    <header>
      <h2>API Documentation</h2>
      <div>
        <label for="version">Version: </label>
        <select id="version" onchange="loadSpec()">
          <option value="./v1/greetings-v1.yaml">v1</option>
          <option value="./v2/greetings-v2.yaml">v2</option>
          <option value="./v3/greetings-v3.yaml">v3</option>
        </select>
      </div>
    </header>

    <!-- ReDoc container -->
    <div id="redoc-container"></div>

    <!-- ReDoc script -->
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
    <script>
      function loadSpec() {
        const version = document.getElementById("version").value;
        Redoc.init(version, {}, document.getElementById("redoc-container"));
      }
      // Load default (v1) on first load
      window.onload = loadSpec;
    </script>
  </body>
</html>

How to Validate the API Specs

Earlier in this article, I mentioned testing your specification locally. Now that you have two more versions of the greetings API, run the test to highlight and fix any existing errors.

• For the version V2: redocly lint v2/greetings-v2.yaml

• For the version V3: redocly lint v3/greetings-v3.yaml

How to Update the GitHub Actions Workflow

Now that you have three API Spec versions, you need to update your workflow so it will monitor the three spec files and the HTML document for changes, and then push and deploy them to GitHub Pages as well.

Add this to your .github/workflows/docs.yml:

# Name of the workflow
name: Build and Deploy API Documentation

on:
  push:
    branches: [ main ]
    paths:
      - 'docs/index.html'
      - 'v1/greetings-v1.yaml'
      - 'v2/greetings-v2.yaml'
      - 'v3/greetings-v3.yaml'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: write

    steps:
      # 1. Checkout the repository
      - name: Checkout repository
        uses: actions/checkout@v4

      # 2. Create build directory
      - name: Create build directory
        run: mkdir -p public

      # 3. Copy YAML specs into public folder
      - name: Copy v1 spec
        run: mkdir -p public/v1 && cp v1/greetings-v1.yaml public/v1/

      - name: Copy v2 spec
        run: mkdir -p public/v2 && cp v2/greetings-v2.yaml public/v2/

      - name: Copy v3 spec
        run: mkdir -p public/v3 && cp v3/greetings-v3.yaml public/v3/

      # 4. Copy landing page into public
      - name: Copy landing page
        run: cp docs/index.html public/index.html

      # 5. Deploy to GitHub Pages
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

And finally, push the changes and reload the site. This should showcase the updated documentation.

Summary

In this tutorial, you have learned how to auto-update your API docs. We started with a single OpenAPI spec and a basic HTML page rendered by Redocly, and tested it locally. We then set up GitHub Actions to automatically validate the spec, copy the files, and deploy the docs to GitHub Pages. Finally, we extended the setup to handle multiple API versions in one place.

With this workflow, your documentation stays accurate, up-to-date, and hassle-free so every change you make to your API spec goes live when you push the changes.

Documentation as code, or docs as code, is an approach to managing documentation that treats the docs like a codebase. It lets you version, automatically update, and review your docs just like you would do in a codebase. Docs as code helps you make sure that your docs are up to date and that users can gain access to accurate information.

This tutorial will show you how to:

• Create a documentation website using Docusaurus.

• Track changes with Git and GitHub.

• Build and deploy it to a hosting platform.

• Set up a workflow to perform grammatical reviews using GitHub Actions before you merge your changes.

Prerequisites

This tutorial is beginner-friendly, but there are some tools you’ll need to have or know in order to follow along:

• VSCode IDE (or other IDE of your choice).

• Node.js and npm installed.

• A GitHub account.

• A reasonable knowledge of how to use Git and GitHub.

Why Do Technical Writers Use Docs as Code?

Before we dive in, let’s quickly talk about what "docs as code" is and why it matters. Back in 2015, two technical writers at Google came up with the idea to make it easier for developers to contribute to documentation and to better organize their company documents. There were times when they needed to write about an application they were working on, but things were really disorganized. So they came up with this process. Since then, many companies have adopted the approach.

Docs as code is now a popular approach to managing documentation, and it’s supported by many tools that are designed to treat documentation like code. Tom Johnson explains this concept in more detail in his article on docs as code.

Traditional documentation relies on Word documents and PDFs, where changes are tracked manually or through document revision history. Writers must update and publish content manually, with no way to automate routine tasks.

On the other hand, docs as code borrows principles and tools from software development to make documentation more structured, versioned, and automated. The documentation is stored in version control (like Git), written in lightweight markup languages, and gets updated alongside the code.

This approach ensures that documentation evolves alongside the software, maintains high quality, and allows for efficient collaboration, just like writing code.

Tools We’ll Use in This Tutorial

Let’s review the main tools we’ll be using for this tutorial:

1. Docusaurus is a tool created by Facebook for creating documentation websites. It supports markdown and mdx. It also supports versioning and custom themes, making it easy to create user-friendly and professional docs.

2. Vale is a customizable style and grammar checker for writers. It ensures consistent language, tone, and style across technical documents. There are other good linters you could use for review apart from Vale, but that’s what we’ll be using here.

3. GitHub Actions: A CI/CD tool for automating workflows directly in GitHub. It helps you test, build, and deploy code with ease.

Step 1: Install Docusaurus

Open your command line terminal and enter the following:

npx create-docusaurus@latest docs-as-code-tutorial classic

docs-as-code-tutorial is the name I am using for the site. You can replace it with any other site name if you wish. Select JavaScript as the language you want to use. This will begin to create a new Docusaurus site. After running the code, you’ll see the docs-as-code-tutorial folder in your VSCode workspace. Navigate to the folder.

Next, start the development server so you can see your docs.

cd docs-as-code-tutorial
npm start

With this, the site will start running at localhost:3000.

When you view the site, you’ll see pre-generated content. So, in the next step, you’ll to create a repository and link the local folder to your remote repository.

Step 2: Create a Repository

Now, you need to create a repository for the docs-as-code-tutorial. So go to your GitHub account and create a new repository.

After creating the repository, you’ll need to link the repository to the folder in your VSCode workspace.

Open a new terminal and run these commands:

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/myname/docs-as-code-tutorial.git
git push -u origin main

With that, you have linked the repository, and Git will start tracking your changes.

Step 3: Customize your Docs in the docusaurus.config File

Before you begin customizing, create a branch where you can make your changes as you push it to the main branch.

git checkout -b "new_branch"

The docusaurus.config.js file is where you can make most of the edits to your site. Change the title property to Docs as code.

const config = {
  title: 'Docs as code',
  tagline: 'Documentation as code',
//rest of your code
   navbar: {
        title: 'Docs as code',
//rest of your code
  }
}

That will show as the new title when you preview the docs. This is simply an illustration to display how Docusaurus works. You can further customize the site to your desired style, but we won’t go into more detail on that here (as the main purpose of this tutorial is to show how to set up your docs as code).

After making the changes, the site should look a bit different.

You can push the changes now.

git commit -am "first commit"
git push --set-upstream origin new_branch

Step 4: Edit Your Docs

For this tutorial, I’ll be making edits in the docs section. Go to intro.md and replace the markdown text with this writeup:

# How to set up docs-as-code

Documentation-as-code is a great means to push changes made in your local machine to your docs live site. To accomplish this, you need an IDE, a static site generator, a Git repository, CI/CD to set up workflows, and a hosting platform. 

## Why do technical writers do docs-as-code?

Documentation-as-code is a great means to push changes made in your local machine to your docs live site. To accomplish this, you need an IDE, a static site generator, a Git repository, CI/CD to set up workflows, and a hosting platform.

After making the edits, preview your docs.

Step 5: Add the Linting Feature

Add the Vale linter to your docs to review errors. To do that, install the Vale CLI with any of these commands.

• Run choco install vale for Windows

• brew install vale for MacOs, or

• snap install vale for Linux

How to set up Vale

As I mentioned earlier, Vale is a customizable style and grammer checking tool. This means you can set it up to review your docs exactly how you want.

Vale uses the Vale style guide when performing reviews to spot errors and make suggestions. But you can add your company’s style guide or any other style guide to it if you prefer. There are public style guides you can use like the Google style guide, Microsoft style guide, and so on. For this tutorial, we’ll be using the Microsoft style guide.

If you don’t already have it, you’ll need to get the Microsoft style guide, download it, and unzip it. Create a styles folder and move the Microsoft folder to the styles folder.

This should be your file path:

- docs-as-code-tutorial
  //other folders
  - styles
    - Microsoft
  //other folders

In your docs, create a .vale.ini file and add it to your root.

Add this code in it:

StylesPath = styles

MinAlertLevel = suggestion

[*.md]

BasedOnStyles = Vale, Microsoft

Let’s understand what’s going on here:

• The StylesPath is set to the styles folder where you added the Microsoft style guide you downloaded. The MinAlertLevel sets Vale alerts to suggestion – this means that Vale will highlight suggestions, warnings, and errors found in your docs. If the MinAlertLevel is set to errors, then Vale will highlight errors only. If set to warnings, then it’ll highlight warnings and errors (and so on).

• [*.md] tells Vale to go through .md files only.

• BasedOnStyles indicates which style guide you are using for the linting. In this case, it’s the Microsoft style guide and Vale style guide. So when the linter is running, it will highlight suggestions, warnings, and errors using the specified style guides.

To test your docs, run vale intro.md (assuming you still have the intro.md file).

This should be the output:

✔ 0 errors, 0 warnings and 0 suggestions in stdin.

Step 6: Build the Site

To do this, run npm run build. After that, you can preview the build with npm run serve.

Step 7: Deploy the Site

There are different hosting platforms where you can host your live site. This tutorial covers two hosting options: GitHub Pages and Netlify.

Deploy with GitHub Pages

To deploy to GitHub Pages, you’ll need to set your repository name and GitHub username/organization name in the docusauraus.config.js file.

// Set the production url of your site here

  url: 'https://ezinneanne.github.io/',

  // Set the /<baseUrl>/ pathname under which your site is served

  // For GitHub pages deployment, it is often '/<projectName>/'

  baseUrl: '/docs-as-code-tutorial/',

  // GitHub pages deployment config.

  // If you aren't using GitHub pages, you don't need these.

  organizationName: 'ezinneanne', // Usually your GitHub org/user name.

  projectName: 'docs-as-code-tutorial', // Usually your repo name.

You can deploy the site to GitHub Pages in the following ways:

• Using the Powershell terminal with this command:

  cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'

• Using the Windows Command line terminal with this command:

  cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"

• Using Bash with this command:
  GIT_USER=<GITHUB_USERNAME> yarn deploy

Just make sure you replace <GITHUB_USERNAME> with your username on GitHub.

Voilà! The site is deployed at https://ezinneanne.github.io/docs-as-code-tutorial/.

Deploy with Netlify

To deploy to Netlify, you only need the production URL and base URL:

// Set the production url of your site here

  url: 'https://docs-as-code-tutorial.netlify.app',

  baseUrl: '/',

1. Go to your Netlify account and link your repository.

2. Click on Add new site.

3. Click on import an existing project.

4. Connect to your GitHub account and select the docs-as-code-tutorial repository.

5. Give your site a name, it should be the same as the URL in your docusaurus.config.js.

6. Add the publish directory which is build and the build command which is npm run build. Then Netlify will deploy to your default branch main, unless you specify otherwise.

7. Finally, deploy!

You should see the site running at https://docs-as-code-tutorial.netlify.app/.

For other deployment options, you can check out the Docusauraus documentation.

Step 8: Set Up a Documentation Workflow Using GitHub Actions

Now we’ll set up a workflow for the documentation. In GitHub, when you deploy to GitHub Pages, it sets up a default workflow for you at pages-build-deployments.

Netlify also automates deployments but does not create a workflow file in your repository. Instead, it manages the process through its platform, monitoring your repository for changes and running builds based on your settings. In this tutorial, we will set up a workflow with GitHub Actions that automates Vale running linting checks through the docs.

Create a .github/workflows directory and add a vale-linter.yml file in it.

Add this code in it:

name: Vale Lint Checker

# Trigger the workflow on specific events.
on:
  push: # Run on every push to the main branch.
    branches:
      - main
  pull_request: # Run on pull requests targeting any branch.
    branches:
      - '*'
  workflow_dispatch: # Allow manual triggering from the Actions tab.

jobs:
  prose:
    runs-on: ubuntu-latest
    steps:
      # Step 1: Check out the repository code.
      - name: Checkout Code
        uses: actions/checkout@v3 

      # Step 2: Set up Node.js
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16 # Use Node.js 16 or higher

      # Step 3: Run Vale lint checks.
      - name: Vale Lint
        uses: errata-ai/vale-action@reviewdog
        with:
          files: .
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

After making these changes, run the following commands:

git add .
git commit -m “changes”

Finally push to the repository with git push.

Go to the Actions tab on your repository. You should see the workflow running:

Click on the changes button and click on the job prose.

Now, you should see all the lines in your .md files highlighted by Vale.

With this, your docs are set up to run like a codebase! You can make changes, and when you push, review, and merge, it will sync automatically.

Keep in mind that this is for Netlify. For GitHub Pages, you’ll need to set up a workflow for automatic deployment.

Summary

In this tutorial, you have learned how to set up documentation as code using Docusaurus. You also saw how to deploy your documentation to a live site, and automate the linting workflow with Vale and GitHub Actions.

There are other workflows you can set up to ease the workload in managing your doc site. Remember, the main point is to organize and structure your docs while automating regular documentation practices using software development tools. This lets you focus on the most important thing which is creating quality content for your readers.

Web accessibility aims to make it possible for anyone to access web content. There are common accessibility best practices for designers, developers, and writers. This article will cover some best practices for creating technical content.‌

What is Web Accessibility?

Web accessibility is the practice of making it possible for anyone to consume or create content on the web, regardless of any health, economic, geographic, or language challenges they may have.

Why is Web Accessibility Important?

It is important to apply web accessibility best practices in your projects for a number of reasons.

First, it'll help you reach a wider audience. When a person who may have different abilities comes across some data on the web – say on your website – they'll want to learn more or use the data. But if they are not able to access it, you will not be happy or have a good experience.

Imagine how many people are unable to utilize the web because they are not considered when devs and designers are making decisions about how the product, website, or tool will be built.

Another important thing about accessibility is that it improves your brand's quality. Letting people know you are an accessibility-oriented person or company by implementing it in your work shows that you want your information to be available t everyone. It also displays your versatility in your craft and your ability to improve and adapt with changing times and trends.

Also, as an individual, applying accessibility best practices benefits you as well. There are possible employment opportunities for developers and designers with great accessibility skills.

Good accessibility practices mean good SEO practices too, which can result in more visibility for your work.

Finally, accessibility is enforced by law in certain countries around the world, and web accessibility strategies are implemented by certain countries. There could be legal consequences if you overlook accessibility on your websites and apps.

How to Write Accessible Technical Documentation

Software engineers have a key role in making the web accessible. But when it comes to writing documentation, technical writers also have a role to play in improving web accessibility.

Technical writers help write various types of content, like user guides, tutorials, API references, code documentation, and so on.

Now, let's look at some of the best practices for implementing web accessibility in technical writing. These strategies will help improve your documentation and make it more user-friendly and accessible to everyone.

Use clear headings and paragraphs

When writing content, you should make sure to use headings – along with the proper heading hierarchy (H1 for the title of the page/article, H2 for major headings, H3 for subheadings, and so on).

Also, make sure to break your content up into paragraphs so it's easier to read and understand.

When you introduce a new topic, use a heading to call that out. When you talk about smaller topics within that section, use subheadings to alert the reader.

Headings are also important to help screen readers understand a page's contents and how to navigate through them. So use headings to help guide readers through the text in a logical manner.

You denote headings in markdown with hashes. Here's an example of headings in hierarchical order.‌

# Use H1 for the page title

## Use H2 for major headings 
This heading is a main heading for the main section content. 

### Use H3 for subheadings 
This heading is a subheading that goes deeper into one of the main section's points.

Make your content clear and concise

Overall, try to keep your sentences quite short in your docs. This makes them easier to read and understand (for everyone). You can also use images or videos to provide more details if needed.

Make sure you give the full meanings of any acronyms you are using for the first time. Also, always use simple sentences, and try not to use ambiguous words.

Here's an example of an overly complex, long sentence with difficult vocabulary:

The web3 running on the Blockchain structure which is transparent, secure, immutable, decentralized would require the processes of artificial intelligence, where it would read data, process, and store information.

This is better:

Web3 is built on the transparent, secure, unchangable, and decentralized structure of the blockchain. It uses artificial intelligence processes to read, process, and store information.

Your content should contain the main points you're trying to make, removing all forms of ambiguity.‌ ‌

Use informative link text

All your in-line links should use clear, detailed, and descriptive text. You can describe the link's purpose or the company's name if it is a brand, for example.

Links are important for improving the ranking of a page. And using links like "Click here" or "Read More" is not all that helpful, as they don't tell the reader much about what they'll find at that link.

For instance, if I wanted to link a W3C (World Wide Web Consortium) accessibility tutorial to this article, I could use the following format: Check out these resources for content writers by W3C.

Add alt text and captions to media content

Images

Adding descriptive text to the alt text attribute allows screen readers to be able to read out the alt text associated with an image. Alt text also helps search engine bots that crawl the page know how to classify that content.

When you're adding alt text, describe the purpose of the image and not what the image is. For instance, let's say you're using an image that shows some shipping containers in a section that is about containerization.‌

Various containers on a ship in motion to illustrate the packaging structure and process of a digital container.

Instead of writing alt text like "various containers on a ship in motion", you could write "various containers on a ship in motion to illustrate the packaging structure and process of a digital container."

While alt text serves as an alternative for the image, captions give more details about the image. You can use HTML to insert image captions. Markdown does not support image captions, but markdown documentation sites usually have a way around it (for example, through plugins – ReadTheDocs, MkDocs – or inserting HTML via a custom component –Docusaurus).

As an example, I'll show you how to add image captions in Docusaurus.

How to add image captions in a Docusaurus .md file:

• Create a folder components in the src folder.

• Create a file named figure.jsx.

• Add this line of code to it:

import React from "react"; 
import useBaseUrl from "@docusaurus/useBaseUrl"; 
export default function Figure({ src, caption }) {
  return ( 
  <figure> <img src={useBaseUrl(src)} alt={caption} /> 
  <figcaption>{`Figure: ${caption}`}</figcaption> </figure> 
  ); 
}

• Go to the .md file where you have the image and import the code.

import Figure from '@site/src/components/figure'; 
import figure1 from 'path-to-image';

• Add it to the file.

<Figure caption="This is a caption for the image" alt="This is alt text" src={figure1} />

The image will now display with a caption.

A screenshot example of image caption

‌Videos

To caption videos, HTML is a great option. But if you are using markdown, you can embed videos from YouTube and Vimeo using the <iframe> tag. These apps offer in-built caption support so you can enable captions before adding the embed code.

You could also install third-party plugins for this purpose.

Here's another tip: avoid flashing content in your videos as it could lead to seizure triggers. If your video has flashing bright colours, ensure that it does not exceed two times within a second.

Add transcripts to audios and videos

It's a good idea to add transcripts to your audio and video content. Not everyone will want to watch or listen to the content. But they may be curious to know what it is about.

By adding a transcript, you make it easier for anyone to navigate through the content and get the information that they need.

Transcript for audio

For audio content, you can insert transcripts using HTML. Here's an example:

<audio controls muted><!--Always set your audios to muted--> 
    <source src="ringtone.mp3" type="audio/mpeg"></source> 
</audio> 
<code> 
    <p>Here is a transcription of the text</p> 
    00:03 = I am going to be productive today<br><br> 
    00:05 = I am going to be productive today<br><br> 
    00:08 = I am going to be productive today<br><br> 
    00:10 = I need to be productive today<br><br> 
    00:11 = I have to be productive today<br><br> 
    00:13 = I should be productive today<br><br> 
    00:16 = I am going to be productive today<br><br> 
    00:18 = I ought to be productive today<br><br> 
    00:21 = I have to be productive today<br><br> 
    00:23 = Productivity matters to me <br><br> 
</code>

For markdown documentation sites like Docusaurus, you can create a custom component.‌

• In your src/components folder, create a file named transcript.jsx.

• Insert this code:

import React, { useState } from 'react'; 
export default function Transcript({ }) { 
  const [showTranscript, setShowTranscript] = useState(false); 
  const toggleTranscript = () => { 
    setShowTranscript(!showTranscript); 
  }; 
  return ( 
    <div> <a href="#" onClick={toggleTranscript}> { 
    showTranscript ? 'Hide transcript' : 'View transcript'
    } 
    </a> {showTranscript && ( <div id="transcriptText"> (insert your transcript text here) </div> )} 
    </div> 
  ); 
}

• Go to your markdown file and import it.

import Transcript from '@site/src/components/transcript'; 

<Transcript />

‌

A screenshot of the audio transcript output

‌Note: I added some tweaks to the code to make transcript display optional. You can edit it if you want the transcript to show as the page loads.

Transcript for video

Now for videos, YouTube is a great option. It provides inbuilt transcripts for your videos. So, you can always embed YouTube videos in your docs.

The transcript is in the video description after the main details. The transcript will display with the timestamps when you click the "Show Transcript" button.

Add code snippets and use the colour contrast technique

How to add code snippets

Use code blocks within the text to explain code instead of images. You could also use code snippets to showcase the output of your code. Unless it is necessary to add an image, you should use code snippets.

For instance,

index.html

<!DOCTYPE html> 
<html> 
    <head> 
        <meta http-equiv="content-type" content="text/html; charset=utf-8" /> <title>A calculator app</title> 
        <link rel="stylesheet" href="styles.css"/> 
    </head> 
    <body> 
    </body> 
</html>

This will allow screen readers to read through the code, which they are not able to do with screenshots.

A screenshot of the above code

Colour contrast technique

The colour contrast technique implies using colours that are opposite or heavily contrasting.

For example, using black text on a white background has a high contrast, as opposed to using light brown text on a brown background.

When combining colours, you could use an accessible colour palette like Color Safe.‌

Using a pale white colour on a green background gotten from Color Safe

Add translation options

There are documentation sites that provide translation options where you can build your docs in multiple languages, websites like Jekyll. This is an example.

Docusaurus is also another doc site that provides multilingual options using Crowdin or Git.

• Follow through this guide to set up translation and localization on Docusaurus using Git.

• Follow through this guide to set up translation and localization on Docusaurus using Crowdin.‌

Use accessibility testing tools

There are tools you can use to check for errors in accessibility in your docs. Some examples are WAVE (Web Accessibility Evaluation Tool) and AXE (Accessibility Engine).

Also, you can get the NVDA(NonVisual Desktop Access) screen reader to test out your content. This software will let you know how the content of your documentation will be perceived by a user using a screen reader.‌

Set up an improvement or suggestion box

Finally, it may not be possible to cover the needs of every user. So you could add a suggestion or improvement box, allowing users to send feedback about how you could further improve the content. Hearing firsthand from users can help you know how best to make the docs accessible for them.

To add an improvement box, you could use an external form link that stores the users' inputs or you could set up the suggestion box in the docs.

How to add an external form link in Docusaurus

You would need to create a custom component for that.

• Go to src/components folder and create a file feedback.jsx.

• Add this code:

import React from 'react'; 

export default function FeedbackButton({ href }) {
  return ( <a href={href} target="_blank" rel="noopener noreferrer" > Give Feedback </a> ); 
};

• In your markdown file import it:

import FeedbackButton from '@site/src/components/feedbackbutton';

• Insert the link

<FeedbackButton href="https://forms.google.com" />

When you run it on your docs, it should showcase a link to Google forms. Google Forms is an example, you could add the link to your company website or server. Here's what it'll look like:

A feedback link for suggestion in a docs site

Summary

To follow and implement these accessibility best practices, you can consider creating or using an already made style guide. This can help you consistently implement these practices and make it easier for you and other technical writers on your team.

There are style guides focused on accessibility for technical writers, such as the following:

1. Accessibility style guide by Heyawhite

2. Write accessible documentation by Google for developers

3. Writing for Accessibility by MailChimp content style guide

That sums up my tips about web accessibility practices in writing. I'm a technical writer, and you can reach out to me on Instagram or hire me via Upwork. Thank you for reading.‌

Today, companies like Spotify apply DevTestOps in software production which makes it easier for them to update, test, and deploy any changes quickly and easily.

In this article, we are going to look at DevTestOps, its objectives, and processes. We'll also look at how to get started with DevTestOps, best practices, and why a company should adopt DevTestOps.

Before we dive into DevTestOps, let’s look at what DevOps and TestOps are and how they work.

What are DevOps and TestOps?

DevOps is a combination of Development and Operations. DevOps was introduced in the software development life cycle because of the need for continuous product development. It helps teams more easily integrate and deploy software updates.

TestOps involves carrying out large automation test suites across software so that the software is highly efficient with fewer bugs.

Initially, DevOps was introduced in software teams which enabled collaboration across developers and operators only. Then testers carried out tests towards the end of development.

This posed some challenges to the team, though. Especially after working on some software and concluding it was ready for production – only for the testers to run it and discover complex bugs. It was through these challenges that DevTestOps came to be.

What is DevTestOps?

DevTestOps is a pattern and part of the software development life cycle that includes continuous testing, integration, and deployment.

In DevTestOps, you test the product throughout the different development stages, which helps reduce the number of bugs at later stages.

In DevTestOps, the Development, Testing, and Operations Teams work hand in hand to ensure quality and proper product testing.

This results in quick delivery, with few to no bugs at the end of the software development lifecycle.

DevTestOps came about as an improved version of DevOps with TestOps included. This makes it easier to build, deploy, and develop quality products with fewer bugs.

Objectives of DevTestOps

DevTestOps has objectives that are called manifestos. The manifestos define the goals that you expect to achieve.

According to mabl.com:

"There are five manifestos of DevTestOps which include: Continuous testing over testing at the end. Embracing all testing activities over only automated functional testing. Testing what gives value over testing everything. Testing across the team over testing in siloed testing departments. Product coverage over code coverage." (Source: mabl.com)

How DevTestOps Works

There are various stages of the DevTestOps process. These stages are:

1. Plan: In this stage, you define product details and cross-check to make sure everything aligns with the market.

2. Build: In this stage, you build the program and upload it to the repository, carry out unit tests, and if you found the program to have no bugs, then it becomes the codebase. You can add possible updates (suggestions or improvements) before moving to the next stage.

3. Testing: In this stage, you carry out and analyse all test cases. You can make subsequent updates and test the program again before delivering it and considering it ready for deployment.

4. Release: You launch the product and test other written updates before it is added to the codebase.

5. Monitor: You constantly check the product for feedback and issues which are handled and updated immediately.

How to Get Started With DevTestOps:

Many organisations already use DevOps but keep producing buggy software. If you want to switch to DevTestOps to try to reduce the bugs in your code, here are some steps you can follow.

Add continuous testing to yout DevOps roadmap or guide:

DevTestOps has a similar culture to DevOps except that in this case, you add continuous testing. Testers should become part of the DevOps team so they can test the software immediately after an update.

Create a DevTestOps toolchain:

A toolchain includes all the tools required to implement DevTestOps. For example, your toolchain might comprise tools like Jira, Kubernetes, Selenium, GitHub, Jenkins and more.

You can assign roles to different teams using these tools so they can work effectively with them.

Implement the tools in your organization:

Next, you'll need to teach teams how to implement these tools and follow the strategies you put in place for software production.

You could add testing roles to each team, which would transform the work culture and encourage collaboration between the developers, testers and operators in each team.

Automation:

You should apply automation in each of these processes, from the build phase to the deployment phase. This will help all the developers and testers work more efficiently.

Make Constant improvements:

Finally, you can constantly update the tools and processes to accommodate relevant trends and updates in the technological space.

Best Practices for DevTestOps:

Here are some best practices you can follow to implement DevTestOps in your team:

• Use the right tools and frameworks for integration, testing, delivery and deployment. This will depend on what works best for the organization.

• Apply automation in testing, deployment, and even other stages as well. Automation will help to speed up the process and make it easier for teams to produce faster and meet with deadlines.

• All teams should communicate effectively. They should promote collaboration across teams to increase understanding which will increase productivity and eliminate confusion.

• The pipeline which comprises continuous integration, testing, delivery and deployment should be monitored always. If you spot a problem, teams can make changes and integrate the updates immediately.

Why Should You Adopt DevTestOps?

‌There are many reasons to adopt DevTestOps. First, it improves code quality.

It also improves collaboration between developers, testers, and operators. Like in the manifesto, testing is no longer done in siloed testing departments but across each phase.

Additionally, it saves time that is spent on fixing bugs when testing at the end instead of in each stage.

And finally, it makes it easier to perform continuous integration and deployment.‌

Conclusion

In a world of constant improvements in technology, companies must continually improve their software to meet market standards.

With DevTestOps, it becomes easier for software teams to make updates and improve their products.

Resources:

• DevOps Advantages And Best Practices | Quick Guide

• What Is DevTestOps And How Can It Transform Agile

• What Is DevOps Orchestration For Agile Teams?