Without API documentation, application development is considered incomplete because developers cannot build software to interact with it, rendering the application effectively useless.

In this article, you will learn how to create beautiful REST API documentation that also allows you to test the APIs for free using an OpenAPI specification and Scalar in Node.js projects. You will use asteasolutions/zod-to-openapi to generate OpenAPI specification and use Scalar to create a web page from the specification.

To get the most out of this article, you should have experience developing REST APIs with Express or NestJS. You should also have experience with documenting REST APIs and using zod.

Table of Contents

• REST API Documentation Tools for Node.js

  • Swagger

  • Postman

  • ReDoc

• zod-to-openapi and Scalar for REST API Documentation

  • How zod-to-openapi Works with Scalar

• Benefits of Using zod-to-openapi and Scalar to Create REST API Documentation

  • OpenAPI Specification Support

  • Open Source and Free to Use

  • Better Documentation Experience

  • Developer-friendly UI

  • Markdown Support

• How to Create the API Documentation

  • Set up the Project

  • How to Set Up zod-to-openapi

  • How to Generate the Documentation UI with Scalar

  • Document the Endpoints

• How to Use Scalar with NestJS

• How to Resolve Content Security Policy (CSP) Errors When Used with Helmet

• Absence of AsyncAPI Documentation Feature

• Conclusion

REST API Documentation Tools for Node.js

A variety of tools already exist for documenting REST APIs and they have different strengths and weaknesses depending on their use case. While some of them are completely free to use, others operate a freemium model, and while some have an interface for testing APIs, others have a presentation-only user interface (UI).

Some of the most popular tools for documenting REST APIs in Node.js projects are listed below:

• Swagger

• Postman

• Redoc

Swagger

In order to document REST APIs in Express with Swagger, you need swagger-jsdoc and swagger-express-ui. swagger-jsdoc collates and parses JSDoc-annotated documentation comments in the codebase and generates an OpenAPI specification document. swagger-ui-express uses the generated document to created a web page that renders the API documentation and test the APIs.

One of Swagger’s strengths lies in its support for the OpenAPI specification which is an industry standard. Swagger is free to use, has a vibrant open source community and strong support for many programming languages and frameworks. It supports only REST APIs.

Its major drawback is the poor developer experience in manually writing JSDoc comments or YAML for the documentation. The process can be clumsy and developers can forget to include some annotations. Another drawback is that the JSDoc comments can interfere with reading functional code. Lastly, some developers have complained about its boring UI.

Postman

Postman is a cloud-based desktop API client application that allows developers and technical writers to write, test, collaborate on and publish API documentation. Unlike Swagger, it does not require deep programming experience to use most of its features. It is also not limited to REST API documentation — it can document APIs for GraphQL, websockets and gRPC.

Postman provides a UI to fill in details of an API documentation. The documentation process is manual and sometimes, its content can get out of sync with that of deployed applications. It is not free to use for teams and collaboration and hides the real behaviour of browser interaction with the APIs like CORS and streaming.

ReDoc

ReDoc is an open-source tool used to generate API documentation from an OpenAPI (Swagger) specification. It supports GraphQL, AsyncAPI and the OpenAPI specification and it renders a more beautiful documentation than Swagger. redoc-express is used to document Express REST APIs with Redoc.

Redoc’s major drawback is that its free community edition is presentation-only. It does not support testing the APIs. Similar to Swagger, a drawback it has is manually updating the application's OpenAPI document via a YAML specification file or JSDoc comments.

zod-to-openapi and Scalar for REST API Documentation

asteasolutions/zod-to-openapi is a TypeScript library that generates OpenAPI specification from zod schemas. It provides typed methods which serve as guardrails for documenting API components instead of using code comments so that:

• The library methods serve as guardrails for what to document and how to document it

• The documentation is consistent across the codebase

• The documentation doesn't negatively affect code readability

A sample snippet used to document a POST request for creating a user with zod-to-openapi is shown below:

// CreateUser and User are zod schema

registry.registerPath({
  method: "post",
  path: "/api/users",
  summary: "Create user",
  tags: ["users"],
  request: {
    body: {
      content: {
        "application/json": {
          schema: schema.CreateUser, 
        },
      },
      description: "Create user payload",
      required: true,
    },
  },
  responses: {
    201: {
      description: "User created",
      content: {
        "application/json": {
          schema: z.object({
            message: z.string(),
            data: schema.User,
          }),
        },
      },
    },
  },
});

Scalar is a tool that generates beautiful, organized and searchable API documentation from OpenAPI documents. The documentation generated also supports testing the APIs and this makes Scalar effectively function as an API documentation generator and a lightweight API client. The image below shows a sample documentation generated by Scalar:

How zod-to-openapi Works with Scalar

zod-to-openapi provides the functionality to generate an OpenAPI specification from code. Scalar uses the document generated to create a documentation web page that presents the information in the document in an organized and beautiful way that also allows for testing the APIs.

Benefits of Using zod-to-openapi and Scalar to Create REST API Documentation

When you combine zod-to-openapi and Scalar to create REST API documentation for your Express applications, you get a myriad of benefits. Some of the benefits are explained below:

OpenAPI Specification Support

The OpenAPI specification is a format for describing REST APIs. It takes takes into consideration the important components of an API necessary for clients to use it effectively. These components include:

• Request paths, methods, headers, path parameters and query parameters,

• Schemas of request and response payloads,

• Authentication requirements,

• Descriptions for information not accommodated by other components

zod-to-openapi provides methods for all of these to be included in the documentation and it generates an OpenAPI specification-compliant document that Scalar uses to generate the documentation web page.

Open Source and Free to Use

zod-to-openapi is open source and free to use. It has no plans to be unsupported or sunsetted soon because like Ruby on Rails and Laravel, the creators of the project use it in their day-to-day work.

Scalar is open source too. It has paid plans but the features in the paid plans are only really useful for enterprise applications. The free version supports the necessary features needed to create useful REST API documentation.

Better Documentation Experience

In terms of user experience, the union of zod-to-openapi and Scalar provides the following benefits when writing documentation with both tools:

Guardrails with zod-to-openapi Methods

The methods provided by zod-to-openapi serve as guardrails to ensure that developers don't omit or forget the documentation of important components of APIs. The methods also ensure that these components are documented in an OpenAPI specification-compliant manner through the typed nature of the methods' parameters.

Avoid the Clumsiness of Comments and YAML Files

With zod-to-openapi, you don't document the APIs using comments or a YAML file. You document APIs using methods from zod-to-openapi. This removes the cluttering of code with comments and the clumsiness around manually updating large YAML files of OpenAPI specification.

Accuracy and Auto-generation of Documentation

When you use zod-to-openapi and Scalar, your API documentation is generated automatically when the application runs. zod-to-openapi does the collation and compilation of the documented APIs, and Scalar creates a web page for it that can be hosted on an API route of the same application. You don't need to manually run CLI commands to generate the documentation.

Another benefit of accuracy and auto-generation is that the job of API documentation is not split between technical writer and backend developer. The documentation is in the code and this makes development faster and more seamless in terms of API documentation.

Developer-friendly UI

While Swagger’s UI is functional, some developers consider its presentation somewhat minimal, particularly when displaying detailed endpoint descriptions. ReDoc improves on visual design but does not offer API testing features. Scalar, on the other hand, delivers a more refined and intuitive interface with greater customization options than ReDoc.

Beyond its design advantages, Scalar provides auto-generated code samples in multiple programming languages. This enables developers to integrate APIs more efficiently using examples tailored to their specific tech stack.

Scalar's UI provides a search feature that allows developers to quickly locate specific sections of the API documentation. It also includes an AI chat interface that enables users to understand how different API endpoints can help address their specific use cases. This approach is more efficient than manually reviewing the entire documentation.

Lastly, you can test the API endpoints from the UI. When you make authenticated API requests, the UI caches authentication tokens so that you don't have to type or paste them for subsequent requests.

Markdown Support

zod-to-openapi and Scalar have Markdown support. With Markdown, you can include conceptual documentation and more information about API endpoints that are not supported by the default documentation components like headers and the request body.

You can embed images, include tables and format text in the documentation. You can use Markdown to include notes that explain concepts related to the API.

How to Create the API Documentation

In this section, you will create an Express CRUD API project that uses zod-to-openapi and Scalar to document its APIs. To practice along, clone the Express starter project from GitHub at orimdominic/freeCodeCamp-zod-to-openapi-scalar.

Set up the Project

After cloning the project:

• install its dependencies using your preferred Node.js package manager

• start the server using the serve script

# Install dependencies
npm install

# Start the application
npm run serve

You should see the following output on the terminal if the application runs successfully:

> freecodecamp-zod-to-openapi-scalar@1.0.0 serve
> node --experimental-strip-types --watch src/index.ts

Listening on :3000

The project has two modules - Users and Pets.

The router configuration for each module is defined in the router.ts file, while the route controllers are located in the controllers.ts file within each module's folder under src/modules. The controllers do not contain business logic, they simply respond with JSON values generated by the Faker library.

How to Set Up zod-to-openapi

Install asteasolutions/zod-to-openapi using your preferred Node.js package manager. If you use npm, run the code snippet below in your terminal:

npm install @asteasolutions/zod-to-openapi

After the installation, create a folder called lib (library) in the src folder. In the lib folder, create a file called openapi.ts. The file will house the code that sets up zod-to-openapi for collating the API documentation and generating the OpenAPI specification.

Copy and paste the code snippet below into src/lib/openapi.ts:

import z from "zod";
import {
  extendZodWithOpenApi,
  OpenApiGeneratorV31,
  OpenAPIRegistry,
} from "@asteasolutions/zod-to-openapi";

extendZodWithOpenApi(z);

export const registry = new OpenAPIRegistry();

export const bearerAuth = registry.registerComponent("securitySchemes", "bearerAuth", {
  type: "http",
  scheme: "bearer",
  bearerFormat: "JWT",
});

export function generateOpenAPIDocument() {
  const generator = new OpenApiGeneratorV3(registry.definitions);

  return generator.generateDocument({
    openapi: "3.1.0",
    info: {
      title: "Users API",
      version: "1.0.0",
      description: `Backend API documentation for users application.`,
    },
    tags: [
      {
        name: "users",
        description: "For operations carried out by admin users",
      },
    ],
    servers: [
      {
        url: "http://localhost:3000",
        description: "Local server",
      },
    ],
  });
}

zod-to-openapi v8 requires zod v4. If you use zod v3, you should use v7.3.4 of zod-to-openapi.

extendZodWithOpenApi is a method provided by zod-to-openapi that enhances Zod schemas by adding an openapi method. The openapi method allows you to attach additional documentation to request payloads, responses, parameters, and their properties, which are then displayed in the API documentation rendered by Scalar.

It is important to call extendZodWithOpenApi before loading any files that use the openapi method, otherwise accessing openapi on Zod objects will result in errors.

An alternative is to use the meta method on zod v4 schemas for the additional documentation. For example, schemaOne and schemaTwo in the code snippet below are the same:

const schemaOne = z
  .string()
  .openapi({ description: 'Name of the user', example: 'Test' });

const schemaTwo = z
  .string()
  .meta({description: 'Name of the user', example: 'Test' });

The meta method supports all metadata information that you'd normally pass to openapi and will produce exactly the same results.

The OpenAPIRegistry is a utility that is used to collate API documentation which would later be passed to an OpenAPI specification generator. registry is created from OpenAPIRegistry, exported, and used to document API endpoints and components in modules where it is imported.

export const registry = new OpenAPIRegistry();

bearerAuth is a component created by the registry to represent JWT authentication. When bearerAuth is included in the documentation of an endpoint, the UI renders an input for submitting an authentication token for authenticated requests as shown in the image below.

In the registerComponent method, "securitySchemes" registers a security scheme component. "bearerAuth" , the first argument of registerComponent, is the name given to the component and it can be changed to a name that you prefer. It appears in the top right of the authentication token input, shown in the image above. The third input to registerComponent is an object that defines the component.

When generateOpenAPIDocument function is executed, it collates all the registry API definitions in the project, generates the OpenAPI specification through generator.generateDocument, and returns the specification as JSON.

The tags property in generator.generateDocument organizes API endpoints into sections on the documentation UI. For example, all API endpoints with the Users tag in their registry definition will be placed under the Users section of the UI. description can be written in Markdown within template literals.

The servers property is a collection of the servers connected to the application. If you have multiple servers, you have the option of selecting what server to use for the base URL in the documentation UI for making API requests from it.

With this setup in place, when endpoints are documented with the registry, generateOpenAPIDocument will have an OpenAPI specification to return.

How to Generate the Documentation UI with Scalar

In this section, you will set up Scalar and connect it to the return value of generateOpenAPIDocument. You will also connect Scalar with an Express route, allowing the application to serve the documentation UI at that route.

Scalar has an Express API reference library that makes it easier for you to connect it with the OpenAPI specification and Express. Install scalar/express-api-reference using your preferred Node.js package manager. If you use npm, use the snippet below:

npm install @scalar/express-api-reference 

Copy and paste the code snippet below into src/app.js:

import express from "express";
import router from "./router.ts";
import { generateOpenAPIDocument } from "./lib/openapi.ts";
import { apiReference } from "@scalar/express-api-reference";

const app = express();
app.use(express.json(), express.urlencoded({ extended: true }));

app.get("/", function (req, res) {
  return res.send("OK");
});

app.use("/api", router);

const apiDocJsonContent = generateOpenAPIDocument();

app.use(
  "/docs", // documentation route
  apiReference({
    content: apiDocJsonContent,
    title: "Users API",
    pageTitle: "Users API",
  }),
);

export default app;

In the code snippet above, generateOpenAPIDocument is imported from src/lib/openapi.ts, and apiReference is imported from @scalar/express-api-reference. When executed, generateOpenAPIDocument returns the OpenAPI specification, which is stored in apiDocJsonContent for caching to improve perfoemance.

A GET /docs route is then created, with the Scalar apiReference function acting as the controller. It accepts apiDocJsonContent and returns a web page whenever the GET /docs route is accessed.

With this setup in place, run the application using npm run serve and visit the documentation page at http://localhost:3000/docs in your browser. You should see a user interface similar to the image below:

To view the codebase at this point, run git checkout set-up-openapi-scalar .

Document the Endpoints

You have set up zod-to-openapi and connected it with Scalar. You have also hooked it up with a route in the backend application. In this section, you will write code to document the endpoints in the application for generating the OpenAPI specification and rendering it on the documentation UI.

To document the route for creating users ( POST /api/users ), in src/modules/users/router.ts , import registry, the schemas and zod using the snippet below:

import z from "zod";
import { registry } from "../../lib/openapi.ts";
import { 
    UserSchema, 
    UserListItemSchema,
    UpdateUserSchema, 
    CreateUserSchema, 
} from "./types.ts";

Copy and paste the code below above the create user route to document the create user endpoint:

registry.registerPath({
  method: "post",
  path: "/api/users",
  summary: "Create user",
  tags: ["users"],
  request: {
    body: {
      content: {
        "application/json": {
          schema: CreateUserSchema,
        },
      },
      description: "Create user payload",
      required: true,
    },
  },
  responses: {
    201: {
      description: "User created",
      content: {
        "application/json": {
          schema: z.object({
            message: z.string().openapi({ example: "User created" }),
            data: UserSchema,
          }),
        },
      },
    },
  },
});

Visit the documentation page and you will find see a web page similar to the image below:

The UI result of some of the input fields of registry.registerPath have been labelled in the image above. The description in the API endpoint is italicised because its value is Markdown in a template string.

By registering the route path for creating users with registry.registerPath and filling its values, you added the documentation of the route to the registry definitions and that makes it included in the OpenAPI specification.

To test the endpoint from the documentation UI:

• click the Test Request button

• fill in the payload in the dialog that appears and

• click the Send button

To document the get user by id route (GET /api/users/:id ), import bearerAuth from src/lib/openapi.ts, copy the code snippet below and paste it above the get user by id route definition.

registry.registerPath({
  method: "get",
  path: "/api/users/{userId}",
  summary: "Get user details by id",
  tags: ["Users"],
  security: [{ [bearerAuth.name]: [] }],
  request: {
    params: z.object({ userId: z.int() }),
  },
  responses: {
    200: {
      description: "User retrieved",
      content: { "application/json": { schema: UserSchema } },
    },
  },
});

When the request.params field is defined using a Zod object, it generates an input UI on the documentation web page that enables users to provide values for path parameters such as userId, highlighted in the image below:

The complete code for the documentation of all endpoints in this section can be accessed when you check out the complete-project branch by running git checkout complete-project in your terminal. It contains documentation for the endpoint for uploading user photo, which demonstrates how to document endpoints that accept file uploads.

How to Use Scalar with NestJS

Scalar has a library that integrates with NestJS. You can use supply the Swagger document created by swagger/nestjs to the Scalar NestJS integration library to generate the Scalar documentation UI.

In root folder of your NestJS project, install the Scalar NestJS integration library:

npm install @scalar/nestjs-api-reference

Update the main.ts file of your NestJS project with the code snippet below:

import { NestFactory } from '@nestjs/core';
import { apiReference } from '@scalar/nestjs-api-reference';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const options = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .addBearerAuth()
    .build();

  const openApiSpecification = SwaggerModule.createDocument(app, options);
  
  // integrate the documentation with NestJS
  app.use(
    '/api/docs', // documentation route
    apiReference({
      content: openApiSpecification,
    }),
  )

  await app.listen(3000);
  console.log(`Application is running on: ${await app.getUrl()}`);
}

bootstrap();

With this setup in place, you can visit the /api/docs route in your browser to view the Scalar documentation for your NestJS application.

How to Resolve Content Security Policy (CSP) Errors When Used with Helmet

If you use Helmet in your Express or NestJS project, you will encounter CSP errors when you try to render the Scalar documentation UI. To resolve the errors, update the Helmet CSP configuration in your code to have the value of the object in the code snippet below:

{
    directives: {
      defaultSrc: [`'self'`],
      styleSrc: [`'self'`, `'unsafe-inline'`],
      imgSrc: [`'self'`, 'data:', 'validator.swagger.io'],
      scriptSrc: ['self', 'https:', 'unsafe-inline'],
    },
  }

Absence of AsyncAPI Documentation Feature

At the time of writing, Scalar does not fully support rendering AsyncAPI specifications for event-driven architecture APIs, although it is currently under development. You can track the progress of its development through the GitHub issue linked in the documentation to stay informed about its release.

Conclusion

You have learned about zod-to-openapi and how it makes it easier for you to generate an OpenAPI specification for your REST APIs than writing comments or large YAML files. You also learned how to use the specification document generated to render a beautiful API documentation UI which also functions as a lightweight API client. Endeavour to implement it in your projects that need a documentation uplift.

Feel free to connect with me on LinkedIn for questions or clarifications. Thank you for reading this far and I hope this helps you achieve what you intended to achieve. Don’t hesitate to share this article if you feel that it would help someone else out there. Cheers!

Before this move, we've had several product releases, and one requirement stayed constant across all of them: the documentation had to be ready at the time of release. This wasn’t because the product was unintuitive or unusable without docs. It was because the documentation was an integral part of the product experience. A release simply wasn’t considered complete without it.

At a glance, this pattern can be dismissed as operational hygiene. After all, good teams ship docs alongside code. But when you look closer, it points to something more fundamental about how users actually experience products today.

For many products, especially developer-facing ones, documentation is often the first real interaction users have with the product. Before they sign up, before they deploy anything, and sometimes even before they talk to sales, they read the docs. This is where they assess whether the product does what it claims, whether it fits their use case, and whether it is worth investing time and effort into.

In practice, documentation often carries more weight than landing pages or launch blogs. Marketing content may introduce the promise of the product, but documentation is where that promise is tested. It turns positioning into reality by showing how things actually work, what trade-offs exist, and how quickly a user can succeed.

Seen through this lens, documentation is not just a supporting artifact but a marketing tool in its own right. It communicates product value, builds trust at the moment of highest intent, and plays a direct role in adoption.

In this article, I want to unpack why documentation functions this way, and why teams should start treating it as a first-class part of their go-to-market strategy rather than an afterthought.

Table of Contents

• The Role of Documentation in a User's Journey

• How to Build Trust at the Moment of Highest Intent

• So, What Actually Builds Trust in Documentation?

• Documentation and Marketing: A Partnership

• Practical Implications: Treating Docs as Marketing

• Conclusion

The Role of Documentation in a User's Journey

The customer journey does not begin when someone clicks “Buy now” or "Start free trial."

Long before that moment, users are already forming opinions about whether a product is credible, usable, and worth their time. In traditional marketing models, this early phase is described as awareness and evaluation. But for technical products, that evaluation phase looks very different from what classic marketing funnels suggest.

Instead of relying primarily on demos, sales conversations, or brand messaging, technical buyers tend to self-educate. Research from Gartner shows that modern B2B buyers spend a majority of their decision-making process researching independently before ever speaking to sales, and this behavior is even more pronounced among technical audiences who prefer primary sources over promotional material.

For developer tools, APIs, and infrastructure products, documentation becomes one of those primary sources. Users move from high-level marketing pages into documentation to answer concrete questions such as how the product works, what it integrates with, what assumptions it makes, and what it will realistically take to adopt. This transition from marketing to documentation is a natural progression in the evaluation process.

In the book The Product Is Docs, the Splunk documentation team describes this transition as needing to be “seamless, cohesive, and logical.” Their point, much more than consistency in tone or branding, is about continuity of understanding.

When users move from marketing content into documentation, they are testing whether the product narrative holds up under scrutiny. If the documentation is incomplete, confusing, or disconnected from what marketing promised, confidence drops quickly, not only in the docs, but in the product itself.

This idea aligns closely with broader research on content-driven buying behavior. Studies on developer experience consistently show that documentation quality is a key factor in product evaluation and adoption. A report by SlashData found that poor or unclear documentation is one of the top reasons developers abandon tools during evaluation, even when the underlying technology is sound.

What this highlights is that documentation does not sit at the end of the user journey, after a purchase has been made. It sits directly in the middle of the decision-making process. It acts as the bridge between curiosity and commitment. Marketing may introduce the problem space and position the solution, but documentation is where users validate whether the solution is real, usable, and aligned with their needs.

The Splunk team refers to this as creating an “integrated content experience,” where marketing and documentation work together to guide users from initial awareness through evaluation, purchase, and successful implementation.

How to Build Trust at the Moment of Highest Intent

When users arrive at your documentation, they’re no longer casually exploring. They’re actively evaluating whether your product fits their needs and whether it’s worth committing time, effort, or money to. This is what makes documentation a uniquely high-intent touchpoint in the user journey.

In marketing terms, high-intent moments are rare and valuable. They occur when users are close to making a decision and are seeking confirmation.

For technical products, documentation is often the primary surface where this confirmation happens. Research from Google on decision-making behavior shows that users rely heavily on “trust signals” at moments of intent, and for technical buyers, accuracy and depth of information matter more than persuasive language.

This is why documentation quality has an outsized impact on outcomes. When users encounter clear and practical documentation during evaluation, confidence increases. When they encounter gaps, inconsistencies, or ambiguity, doubt sets in immediately. Unlike marketing content, documentation doesn’t get the benefit of abstraction. It’s expected to be precise and complete.

Documentation is part of a continuous guide that “holds a customer’s hand” from evaluation through purchase and into successful usage. This framing is important because it highlights that trust isn’t built once and forgotten. It’s maintained across stages. Documentation inherits the trust marketing creates, but it must earn its own by demonstrating technical credibility and practical value.

This is the point where many products fail because marketing successfully drives interest, but documentation breaks the trust loop by failing to support the claims made earlier. When that happens, users don’t just lose confidence in the docs but also in the product and, by extension, the company behind it.

So, What Actually Builds Trust in Documentation?

Trust in documentation isn’t subjective. It’s shaped by specific, observable qualities that users quickly pick up on during evaluation.

Accuracy is the foundation. When examples work as described, and behavior matches documentation, users feel safe moving forward. When it doesn’t, you have a problem. Studies on developer experience consistently rank inaccurate documentation as one of the fastest ways to lose adoption, even when the underlying product is powerful.

Completeness is a signal of maturity. Documentation that covers core workflows, edge cases, and limitations tells users that the product has been thought through. Gaps, missing sections, or “coming soon” pages suggest instability or unfinished work. For evaluators, this raises red flags about long-term viability.

Another point is honesty, which plays an equally important role. Strong documentation doesn’t hide constraints or trade-offs. Instead, it acknowledges them clearly. Research in trust psychology shows that transparency, even about limitations, increases perceived credibility because it reduces uncertainty and surprises later.

Also, more recently updated docs reflect better on team health. Updated documentation signals active maintenance and ongoing investment. On the other hand, outdated docs suggest abandonment or stagnation. For technical buyers, this is often interpreted as a warning sign about support and future development.

Finally, usability determines whether trust can even form. Documentation that is difficult to navigate, poorly structured, or even hard to search fails before its content is evaluated. Nielsen Norman Group’s research on information-seeking behavior shows that users abandon content quickly when they cannot find answers with minimal effort, regardless of quality.

Together, these factors shape how users perceive not just the documentation, but the product and organization behind it.

Documentation and Marketing: A Partnership

In the book The Product is Docs, the authors observe that documentation teams and marketing teams "have more in common than you might think." Both are responsible for communicating product value to audiences, both create content that influences buying decisions, and both play crucial roles in the customer journey.

Yet these teams often operate separately, thereby creating disconnected experiences for users.

Marketing promises capabilities without understanding technical constraints, while documentation focuses on implementation details without connecting to broader use cases or business value.

The result of this is a jarring transition from marketing to product that undermines both efforts.

So, how can marketing help documentation?

Marketing teams bring a valuable perspective to documentation:

• Customer insights: Marketing interacts directly with prospects and customers through demos, events, and demand generation. These interactions surface real questions and pain points that documentation should address.

• Competitive intelligence: Understanding how competitors document their products can reveal opportunities for differentiation or improvement.

• Strategic priorities: Knowing which features marketing will emphasize helps documentation teams focus their effort where it will have the most impact.

• Target audience definition: Marketing's customer research and personas can inform documentation structure and examples.

And...how can good documentation help marketing?

Documentation teams bring equally valuable assets to the partnership:

• Technical accuracy: Documentation teams can review marketing materials for technical correctness and help refine messaging to be both compelling and accurate.

• Content leverage: Well-written documentation can be adapted into blog posts, white papers, and other marketing content.

• User feedback: Documentation teams often receive direct feedback from users about what's confusing or what features resonate most.

• Writing expertise: Technical writers can help develop clearer, more effective marketing content.

The Splunk team emphasizes that this collaboration should span the entire release cycle: "Before you write" (to align on priorities and naming), "As you write" (to validate approaches), and "After you write" (to ensure consistency and quality).

Figure 1: Embedding docs in the release cycle

Practical Implications: Treating Docs as Marketing

If documentation is indeed a marketing tool, what changes in how we approach it?

1. Documentation should ship with product launches

This is where my own experience began. Documentation can't be an afterthought that ships weeks after launch. If docs are part of how users evaluate and adopt the product, they need to be ready when the product is. This means involving documentation teams early in the development process, not at the end.

As the Splunk team notes in their discussion of Agile development: "There is no definition of ‘done’ without docs. Customer documentation is part of the working software." This principle should extend to marketing launches as well.

2. Invest in documentation quality and discoverability

If documentation influences buying decisions, it deserves the same attention to quality and user experience as marketing websites. This means:

• Professional design and navigation

• Fast search functionality

• Clear information architecture

• Mobile-friendly formatting

• SEO optimization for relevant queries

Too often, documentation sites are neglected from a UX perspective while marketing pages receive constant refinement. This sends a message about priorities that users notice.

3. Create an integrated content experience

The transition from marketing to documentation should feel natural. This requires:

• Consistent terminology: Features should be named the same way in marketing materials and documentation.

• Aligned narratives: The use cases highlighted in marketing should have detailed implementation guides in the documentation.

• Cross-linking: Marketing pages should link directly to relevant documentation sections, and vice versa.

• Shared success metrics: Both teams should care about the same outcomes – not just awareness or signups, but successful implementation and adoption.

The Splunk team describes this as helping customers avoid feeling "disoriented or, worse, feel misled." Good documentation delivers on marketing's promises with specifics on how to achieve the outcomes that were advertised.

4. Measure documentation impact on conversion

If documentation is part of the marketing funnel, it should be measured as such. As a documentation team, you should track metrics like:

• Documentation page views from prospective customers

• Time spent in docs before conversion

• Most-viewed pages during evaluation periods

• Correlation between documentation engagement and trial-to-paid conversion

• Customer feedback on documentation quality during the buying process

These metrics help demonstrate documentation's business impact and justify investment in quality improvements.

If you're curious about examples of docs that embody these strategies, then you might want to check out Twilio, Stripe, or, as mentioned earlier, the Splunk docs.

Why does all this matter now?

The role of documentation in driving adoption has always been important, but several trends are making it more critical:

First, as more companies adopt PLG strategies, the product experience, including documentation, becomes the primary sales vehicle. There's no sales team to answer questions or guide implementation. The docs must do that work.

Second, technical buyers increasingly want to evaluate products independently before engaging with sales. Documentation is often their primary evaluation tool.

We’re also seeing shorter sales cycles. When buying cycles compress, there's less time for demos and sales engineering. Documentation needs to answer questions immediately.

And finally, for developer tools and infrastructure products, individual contributors often drive adoption from the bottom up. These users rely heavily on documentation for their evaluation process.

In this environment, treating documentation as an operational necessity rather than a strategic asset is a competitive disadvantage. Companies that recognize documentation as a core part of their go-to-market strategy and invest accordingly see better conversion rates and stronger customer relationships.

Conclusion

Documentation is not just a post-purchase support resource. It's an active participant in the customer journey, influencing buying decisions and driving adoption.

For technical products, especially, documentation often carries more weight than traditional marketing materials.

This doesn't mean documentation should become marketing copy. It means recognizing that documentation performs a marketing function such as communicating value and building credibility, even while maintaining its technical accuracy and practical focus.

As the Splunk documentation team wisely notes, the goal is to create an integrated content experience where marketing and documentation work together to guide users from initial interest through successful implementation.

So, the requirement that documentation be ready at release time wasn't just operational hygiene. It was recognition that our product wasn't truly ready for market until users could both evaluate it and successfully use it. That's what makes documentation a marketing tool, not because it makes exaggerated claims, but because it delivers on the promise that marketing makes.

As an IT support officer, I can put myself in the perspective of a user and identify friction points, but this document had no visuals, no simplified explanations, just walls of backend jargon: service mesh, container orchestration, async queues, REST APIs… you name it.

I realized quickly: if someone like me struggles to understand this, so will PMs, frontend devs, new hires, and even other IT staff.

Here’s a practical guide for creating system architecture documentation that anyone on your team can read and use:

• Step 1: Show the System from Different Angles

• Step 2: Make Diagrams the Star

• Step 3: Translate Tech Into User-Relevant Outcomes

• Step 4: Make Communication Clear

• Step 5: Keep it Simple and Consistent

• System Architecture Documentation Tools for Teams

• Conclusion

Step 1: Show the System from Different Angles

A good architecture doc isn’t just a list of tech terms. Think about who is reading it:

A. Conceptual View (PM/UX/business folks)

• What the system does for the user.

• Example: “User Authentication System,” “Checkout Service”

• Focus on user value and business goals.

B. Component View (frontend developers/IT staff)

• How the parts interact.

• Example: “Web App calls API Gateway → Microservice → Database”

• Focus on data flow and system boundaries.

C. Operational View (backend/DevOps)

• Where the system runs and how.

• Example: servers, databases, cloud setup, scaling.

• Focus on infrastructure and deployment.

This way, everyone can find what’s relevant to their role without getting lost in technical weeds.

Step 2: Make Diagrams the Star

Words alone don’t cut it. Diagrams help people visualize the system, especially if they’re not experts.

Types of Diagrams to Include

• System Context Diagram: Shows the system and its external dependencies. UX/PM/IT staff can see how it touches users and other systems.

• Container Diagram: Shows main boundaries like “Web App,” “Auth API,” “Database.” Frontend and backend teams benefit.

• UML/Component Diagram: Shows internal structure or interactions. Mostly backend focus, but helps everyone understand flow.

Tip: Even a simple flowchart drawn in PowerPoint, Figma, or by hand is better than none. Clarity matters more than perfection.

Diagrams help:

• UX sees user impact.

• Frontend knows which services to hook up.

• Backend sees infrastructure and interactions.

• Everyone shares the same mental picture.

Example 1: System Context Diagram

This diagram illustrates who uses the system (a person on the web) and which external services it depends on, like Stripe for payments and SendGrid for emails. It doesn't show the internal workings of the system, just what it connects to.

Example 2: Container Diagram

This diagram illustrates the main components of the system: the Web App, which is the user interface; the Auth API, responsible for handling login and security; and the User Database, where user profiles are stored. The arrows indicate how these components interact with each other.

Practical Tip: Tools to Create Clear Architecture Docs.

Step 3: Translate Tech Into User-Relevant Outcomes

System architecture goes beyond databases and queues, focusing on making the product fast, reliable, and secure for users. Link technical requirements to outcomes everyone can understand:

Even a person with basic UX awareness can see why tech decisions matter.

Step 4: Make Communication Clear

One major source of confusion is how different parts of the system talk to each other. Spell it out:

a) Frontend ↔ Backend: Clearly explain how your frontend connects to the backend.

Example: “The website sends login requests to the Auth API.”

b) Backend ↔ Backend: Explain whether services communicate with each other instantly (synchronous) or through background tasks like message queues (asynchronous). This helps the team understand why some actions feel instant to users, while others take time.

Even non-backend readers can follow the flow and understand how it impacts the product.

Step 5: Keep it Simple and Consistent

• Use headings, bullet points, and a table of contents. Don’t write a novel.

• Keep names consistent: “User Service” in diagrams should match text labels.

• Explain the “why” behind major decisions:

“We chose a NoSQL DB for User Profiles because it requires fast read/write for non-relational data.”

Consistency and simplicity make the doc useful to everyone, not just backend experts.

System Architecture Documentation Tools for Teams

Great architecture documentation lives where your team already works and uses tools that are easy to update, share, and understand. Below are the common types of tools teams use, grouped by purpose.

Documentation Platforms (Where You Write the Full Doc)

You can use these tools to combine text, diagrams, and structure a document.

Google Docs
Simple, familiar, and collaborative. Supports real-time comments, edit history, and easy sharing. Perfect if your team already uses Gmail or Drive. Just paste diagrams as images.

Confluence
Common in larger companies. Integrates with Jira, supports page templates, and lets you embed diagrams. Good for structured knowledge bases.

Notion
Flexible workspace for small teams. Mix docs, tasks, and diagrams in one place. Great if your team uses Notion for other work.

GitHub/GitLab Wikis (with Markdown)
Ideal for engineering-heavy teams. Docs live next to your code, and you can include diagrams using simple code (like Mermaid). Changes are tracked like code.

Start with Google Docs if you’re unsure. A living doc people actually read is better than a “perfect” one no one opens.

Diagramming Tools (Where You Create Visuals)

These help you draw the architecture diagrams you’ll add to your documentation platform.

Draw.io
Free, browser-based, and drag-and-drop simple. No sign-up needed. Exports clean PNG/SVG files you can paste into Docs or Confluence. Great for C4-style diagrams (System Context, Container, and so on).

Figma
If your team already uses Figma for design, you can create architecture diagrams using basic shapes and arrows. Real-time commenting makes feedback easy. Just export as PNG for Docs.

Mermaid (Diagrams as Code)
Write simple text like User --> Web App, and it becomes a diagram. Works in GitHub, GitLab, and tools like Obsidian. Use the Mermaid Live Editor to design, then download and paste into Google Docs.

A Key Insight from Practicing Architects.

Avoid tools that only produce static images (like PowerPoint, Canva, or basic whiteboards) for anything beyond quick sketches. If the same service appears in three diagrams and you rename it, you’ll have to update all three manually, leading to outdated and inconsistent docs.

How They Work Together

1. Write your doc in Google Docs (or your team’s existing platform).

2. Create diagrams in Draw.io or Figma (or try Mermaid if you’re curious).

3. Paste the diagram into your doc, add alt text, and explain what it shows in plain language.

This combo gives you accessibility, collaboration, and maintainability without overwhelming you or your team.

Conclusion

You don’t need to be a senior engineer to write great architecture docs. You just need clarity, empathy, and the willingness to explain “why.”

Most community managers spend hours each week answering the same questions over and over. You might find yourself repeating instructions for how to join a project, what the process for submitting an event proposal is, or who to contact for a specific problem because "everyone just knows" how things work. The issue is that the information isn't easy to find or understand when your community members need it most.

Effective documentation is the unsung hero of a thriving community. In this tutorial, you will learn how to create documentation that genuinely serves your tech community. You will discover proven techniques for organizing information, writing clear instructions, and building systems that work for both newcomers and experienced contributors.

Table of Contents

• Why Community Documentation Often Falls Short

• Core Principles for Effective Community Documentation

• How to Know Who You're Writing For

• How to Organize Information for Easy Access

• How to Write Instructions That People Can Actually Follow

• Essential Documentation Every Tech Community Needs

• How to Create a New Member Onboarding Guide

• The Community Operating Procedures Handbook

• The Event Planning Handbook

• The Community Guidelines and Behavioral Expectations Handbook

• How to Test Whether Your Documentation Works

• How to Observe How People Actually Use Information

• How to Ask Targeted Questions for Improvement

• How to Monitor Community Health Indicators

• How to Maintain Documentation as Your Community Evolves

• How to Schedule Regular Review Cycles

• How to Create Systems for Community Input

• How to Build Documentation Updates into Regular Workflows

• How to Create a Culture of Clear Communication

• How to Model Excellent Communication Practices

• How to Integrate Clarity into Decision-Making

• How to Recognize Clear Communication

• Conclusion

Prerequisites

To get the most from this tutorial, you should have:

• Experience participating in or managing tech communities.

• Responsibility for creating processes or guidelines that others need to follow.

• Access to community platforms like Slack, Discord, or similar communication tools.

No formal writing experience is required. This guide focuses on practical approaches that work in community settings.

Why Community Documentation Often Falls Short

Documentation often fails because it is created for the wrong audience or stored in a way that makes it difficult to find. A common pitfall is creating documentation that is too technical or formal, using jargon that is not understood by new members. Another issue is that documentation is often a one-time effort, not a living resource. When processes or team members change, the documentation becomes outdated and unreliable, causing people to abandon it entirely.

Core Principles for Effective Community Documentation

Strong community documentation is built on four key principles that make information genuinely useful rather than just comprehensive.

How to Know Who You're Writing For

Different community members need different information depending on their experience level and involvement goals. Consider these main audiences:

• New members who are exploring how to participate.

• Active participants looking for specific opportunities or information.

• Volunteers needing clear instructions for their responsibilities.

• Organizers requiring detailed procedures and decision-making guidelines.

How to Organize Information for Easy Access

The way you structure information is just as important as the information itself. Good documentation anticipates a user's needs, allowing them to find what they are looking for without digging through endless pages.

A well-organized documentation hub should mirror your community's journey. Start with high-level, introductory information and then branch out into more specific, detailed guides. For example, a newcomer should see a clear pathway to finding a welcome guide, while an experienced volunteer should be able to jump directly to a detailed event checklist.

Think about using a central location that is easy to access, such as a dedicated channel, a pinned post in your community platform, or a simple, single-page website. Use subheadings and bullet points to break down long sections of text, making the content scannable and digestible.

How to Write Instructions That People Can Actually Follow

Clear instructions are the bedrock of effective documentation. When you write a guide, imagine you are sitting with a new volunteer, talking them through a task step-by-step. Use active voice and simple, direct language. For example, instead of writing "The event registration form should be created," write "Create the event registration form."

Use numbered lists to guide readers through a process in a logical order. You can use screenshots and diagrams to illustrate a point, but make sure they are clear and easy to understand. For instance, a screenshot of a community's Standard Operating Procedure (SOP) document can help a new team member visualize their tasks.

Essential Documentation Every Tech Community Needs

Different types of documentation serve different purposes in community management. Here are the most important ones to prioritize.

How to Create a New Member Onboarding Guide

Your onboarding documentation should help new members feel welcome and find their first meaningful way to participate. Effective onboarding includes:

• A welcome message explaining community values and culture.

• A quick overview of how to access and use community platforms.

• Immediate ways to get involved that match different comfort levels.

• A community calendar highlighting upcoming opportunities.

• Clear contact information for getting help.

The Community Operating Procedures Handbook

Standard procedures ensure consistent experiences regardless of which team member handles a situation. As community management expert Rosemary O'Neill notes:

"Clear processes are not about bureaucracy – they are about creating predictable, positive experiences that let community members focus on connection rather than confusion."

Comprehensive community procedures should address:

• Team Structure and Operations: Community mission statement and core values, team roles with clear responsibility boundaries, decision-making processes and approval workflows, communication protocols for different situations.

• Member Experience Management: Application review standards and timeline expectations, new member welcome sequence with multiple touchpoints, engagement strategies including regular check-ins and recognition programs, pathway documentation for members to increase involvement, feedback collection methods and response protocols, professional offboarding process for departing members.

• Community Building and Growth: Content creation guidelines and approval processes, partnership evaluation criteria with other organizations, volunteer recruitment strategies and management systems, leadership development opportunities and requirements.

• Event and Program Management: Event planning workflows from initial concept to post-event review, speaker recruitment, vetting, and coordination procedures; registration management and attendee communication templates, technical requirements and setup procedures for different event formats, post-event evaluation and improvement documentation.

• Community Health and Safety: Conflict resolution procedures with clear escalation paths, community guideline enforcement protocols and consequences, crisis communication plans and emergency contacts, member well-being resources and support systems.

• Evaluation and Improvement: Community health metrics and regular assessment schedules, member satisfaction measurement and analysis methods, growth tracking systems and reporting requirements, quarterly review processes and improvement planning.

The Event Planning Handbook

Events often drive community engagement and growth. Your event documentation should enable teams to create successful experiences consistently. Organize event documentation by timeline:

• 6-8 weeks prior: Initial planning, venue booking, speaker outreach.

• 4-6 weeks prior: Registration setup, marketing launch, logistics confirmation.

• 2-4 weeks prior: Final details, volunteer coordination, attendee communication.

• Week of event: Setup procedures, team briefings, backup plans.

• Event day: Detailed checklists for setup, execution, and wrap-up.

• Post-event: Follow-up tasks, feedback collection, documentation updates.

The Community Guidelines and Behavioral Expectations Handbook

Community guidelines should clearly communicate expectations while reflecting your community's specific culture and values. Effective community guidelines include:

• Specific behavioral expectations with concrete examples.

• Clear consequences that focus on community repair and learning.

• Accessible reporting procedures for concerns or conflicts.

• Resolution processes that prioritize healing and growth.

• Recognition systems for positive community contributions.

How to Test Whether Your Documentation Works

Creating documentation is only the first step. You need to verify that it actually helps people succeed in your community.

How to Observe How People Actually Use Information

The most valuable feedback comes from watching interactions between community members and your documentation. Observation methods:

• Ask new volunteers to follow your procedures while you watch (without providing extra help).

• Monitor community channels for repeated questions that suggest documentation gaps.

• Track completion rates for multi-step processes.

• Pay attention to member feedback about confusing or particularly helpful resources.

How to Ask Targeted Questions for Improvement

Generic feedback does not provide enough detail for meaningful improvements. Ask specific questions that reveal actual pain points. Useful feedback questions:

• "At what point did you feel unsure about what to do next?"

• "What information were you looking for that you could not easily find?"

• "If you were teaching this process to someone else, what would you explain differently?"

• "What would have made this experience smoother or more welcoming?"

How to Monitor Community Health Indicators

Good documentation should contribute to overall community sustainability and member satisfaction. Signs that documentation is working:

• Fewer repetitive questions in community channels.

• Higher volunteer retention and satisfaction scores.

• Faster integration of new members into community activities.

• More consistent execution of events and programs.

• Reduced administrative burden on community organizers.

How to Maintain Documentation as Your Community Evolves

Documentation requires ongoing attention to remain useful as your community grows and changes.

How to Schedule Regular Review Cycles

Establish predictable times for updating and improving your documentation:

• Monthly reviews of frequently-used resources like onboarding materials.

• Quarterly comprehensive reviews following major events or program cycles.

• Annual documentation audits to remove outdated information and improve organization.

• Immediate updates when processes change or new information becomes available.

How to Create Systems for Community Input

Make it easy for community members to suggest improvements and contribute updates. Simple contribution methods:

• Feedback forms or shared documents for quick suggestions.

• Regular "documentation improvement" sessions during community meetings.

• Recognition programs for members who contribute helpful updates.

• Clear guidelines explaining how community members can suggest or make changes.

How to Build Documentation Updates into Regular Workflows

Instead of treating documentation as separate work, integrate updates into existing community management processes:

• Include documentation reviews in event planning checklists.

• Assign specific documentation responsibilities to team members.

• Make documentation accuracy part of program evaluation processes.

• Train multiple people to update and maintain critical resources.

How to Create a Culture of Clear Communication

The most effective community documentation happens when your entire team values clarity and considers member experience in every decision.

How to Model Excellent Communication Practices

As a community leader, your communication style influences how everyone else approaches sharing information. Ways to model good documentation habits:

• Always include context when making announcements or giving instructions.

• Follow up on frequently asked questions with documentation improvements.

• Acknowledge and appreciate team members who create helpful resources.

• Treat documentation work as valuable community contribution, not administrative overhead.

How to Integrate Clarity into Decision-Making

Make "Will this be clear to community members?" a standard question in your planning processes. Consider documentation impact when:

• Launching new programs or changing existing procedures.

• Planning events or community initiatives.

• Onboarding new team members or volunteers.

• Responding to community feedback and implementing improvements.

How to Recognize Clear Communication

When community members create helpful resources, explain things well, or improve existing documentation, make sure their contribution is acknowledged and valued. This recognition encourages others to consider community accessibility and take ownership of shared information resources.

Conclusion

Effective community documentation is not about perfect writing or exhaustive detail. It is about understanding what your community members need and creating clear paths for them to succeed.

You've learned how to organize information around member goals, write instructions that prevent confusion, and build systems that keep documentation relevant as your community grows. Most importantly, you've discovered how to promote a culture where clear communication is valued and community accessibility becomes everyone's responsibility.

Remember, this key principle: good community documentation is measured by member success and community health, not by volume or technical perfection. When new members can easily find ways to get involved, volunteers feel confident in their roles, and your community operates smoothly without requiring constant intervention, your documentation is fulfilling its purpose.

Start with one small improvement. Choose a process that generates frequent questions, apply these techniques, and observe the impact on your community's experience. Each improvement is a step toward building a truly sustainable, welcoming tech community where everyone can contribute effectively.

You can also connect with me on LinkedIn, X (Twitter) and Medium. If you made it to the end of this tutorial, thanks for reading!

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.

But if you’re serious about product adoption, your docs need to do more than exist. They need to guide, support, and convert. In this tutorial, we’ll break down how to write documentation that actually helps users and gets them to stick around.

Table of Contents

• What’s the Problem with Most Documentation?

• How to Write Documentation from the User’s Perspective

  • Start by Understanding Your Users

  • Structure Around the Four Documentation Types

  • Make it Easy to Reach Out

  • Keep Your Tech Team in the Loop

  • Reuse What You’ve Already Written

  • Get AI Help (The Smart Way)

  • Get Feedback Early

• How Does Documentation Increase Sign-ups?

• Making Complex Documentation Accessible

What’s the Problem with Most Documentation?

The most common problem with documentation is that its authors believe their audience knows everything. This leads to the loss of many potential leads – causing people to abandon your platform before even fully understanding it.

Here’s why:

• It’s often dry and code-heavy, with snippets and vague bullet points.

• It dumps information and expects the readers to figure it out.

• It’s written from the developer’s point of view, not the user’s.

• It rarely shows how the product fits into the user’s specific use case or workflow.

• It combines different content types into a chaotic mess that’s difficult to follow or navigate.

How to Write Documentation from the User’s Perspective

Most documentation is written from a developer’s perspective: technical, feature-first, and dry. But at the end of the day, developers are also humans with problems like others, and when browsing your documentation, they are asking:

• “Can this solve my problem?”

• “How do I get it working for my use case?”

• “What happens if I get stuck?”

Here’s how you can make people stay and come back to your documentation.

Start by Understanding Your Users

Before writing a single line of documentation, pause and ask: What do our users actually care about? And it's more than just “connect an API to their client’s app”. It's the intangible benefits they’re seeking, such as two hours saved due to your tool while connecting the API or collecting payments from different clients with a single workflow.

This means that you need to listen before you write.

Dig into conversations happening around your product, not just within it. What questions do users consistently ask during sales calls? What pain points come up in Reddit threads or support tickets? What complaints are circulating on social media that haven’t been addressed yet?

Pay close attention to the words they use while referring to your product.

When you use their words, not yours, your documentation starts to sound like a helpful guide, not a technical manual. That shift alone can be the difference between “let me try this tool” and “I’ll figure it out later.”

Supabase is a good example of user-friendly docs. It begins by categorizing content by product, module, and client library. Each category includes comprehensive documentation with real-world examples, practical use cases, tutorials, and built-in feedback support.

Structure Around the Four Documentation Types

Now that you know your customer, your job is to guide them to the correct answer fast. That’s hard to do if everything’s thrown together in one long page. Structure is what turns chaos into clarity.

The best documentation systems categorize information into four types, a framework originally proposed by Divio. Not just different sections, but completely different purposes. Each one meets your user at a different stage of their journey.

Let’s break them down:

1. Quickstart

This is the user’s first real experience with your product, and it’s where they decide whether to continue using it. So your job here isn’t to explain everything. It’s to walk them through one thing that works. Slowly. Clearly. And in their language.

Use examples. Don’t assume prior knowledge. Avoid jargon unless you’ve already explained it. The goal is to create that first “Oh, I get it now” moment. Because once they’ve had it, they’ll stick around for more.

For example, the React documentation gives beginners a simple walkthrough, from creating a component to passing data between them. It avoids jargon, focuses on one working example, and explains each step clearly. This helps users quickly grasp how React works, creating that first “Oh, I get it now” moment.

2. How-to Guides

These are for users who already know the basics and just want to solve a problem. “How do I connect this to Slack?” “How do I export this as a CSV?” They’re not here to learn concepts. They just want to follow instructions and get something done.

Start by telling them exactly what the guide will help them do. List prerequisites up front if needed. Then walk them through the steps.

For example, the TensorFlow documentation includes a step-by-step guide on how to build a Convolutional Neural Network (CNN) to classify images. It’s task-focused and practical, so anyone trying to implement image classification with TensorFlow knows exactly where to go and what steps to follow.

3. Technical Reference

This is where the raw details live. Your endpoints, CLI commands, Parameter lists, what happens when something fails, and so on. Think of it like a glossary of your tool.

People scan this portion of your documentation, so make it easy to scan. Organize it so someone can jump to what they need. Use consistent formatting and avoid explanations here, but add links to the explanations sections.

For example, the Kubernetes documentation includes a comprehensive API reference that lists all available resources, their fields, default values, and behaviors. It’s organized into categories like common parameters and workload resources, making it easy to navigate. Each section focuses on definitions and parameters, with links to related conceptual docs for deeper context.

4. Explanations

This is where you step back and explain the thinking behind your system. Why does your product rely on webhooks? Why did you structure your SDK a certain way? When should someone use one method over another?

This part differentiates your tool from the crowd and builds trust. Yet, many documentations miss this. Don’t forget to add a separate section on common errors beyond 404s here. The errors that people encounter when using your tool provide a straightforward solution to those errors.

For example, Divio has an explanation section in its documentation that covers each relevant concept in detail. It starts by explaining the concept itself, then shows how it works within Divio and what practical applications it has. This helps users understand the reasoning behind the system and how to use it effectively.

Make it Easy to Reach Out

Even with perfect docs, users will get stuck. And the worst thing you can do now is make them hunt for help.

Make it ridiculously easy to reach out.

Add a simple “Was this helpful?” prompt at the end of each page. If the answer is no, give them a quick way to say why.

Drop in a link to report bugs, outdated steps, or confusing content. You’ll get real-time feedback from real users.

Invite them to contact support or drop a question in your community Slack or Discord. It’s not just about solving issues. It’s about showing them you’re listening.

Keep Your Tech Team in the Loop

You don’t need to know how every line of code works. But you do need a clear path to someone who does.

Set up a shared document, Notion page, or Slack thread where your development team can casually share technical decisions, temporary errors, important workarounds, and other relevant information.

Also, don’t be afraid to ask your devs directly. A 3-minute voice note or quick message like “Does this sound right to you?” can prevent a dozen user errors later..

Reuse What You’ve Already Written

Chances are, you've already explained 80% of what needs to go in your docs you just didn’t call it “documentation” at the time.

Start by digging through what’s already there:

• Sales or support Slack threads where you broke things down clearly

• Onboarding emails that walk users through the first steps

• Internal guides your team relies on

• Blog posts where you’ve explained product decisions

• FAQs your support team sends on repeat

Copy-paste, trim, reframe, and you’ve got a doc draft in minutes.

Get AI Help (The Smart Way)

AI tools can cut your documentation time in half, but only if you treat them like a collaborator. One powerful way to use them is by turning raw code into structured docs.

Just drop in a code snippet or feature file and prompt something like: “Write a reference doc for this API endpoint. Include usage, parameters, response structure, and a working example.”

Then take it a step further: “Now rewrite this for a non-technical product manager who’s using the tool for the first time.” This way, you get both the technical version and a plain-English explanation without switching tabs ten times.

I used AI to generate the documentation for the user.updated webhook event, and here’s what it came up with. While the generated doc is functional, I’d like to improve it further.

Here are my initial thoughts:

• Avoid starting with generic phrases like “This document describes...”

• Jump straight into what the user.updated event does

• Remove unnecessary passive voice to improve clarity

• For example, instead of:
  "The user.updated event is triggered when a user's profile is updated in the system."
  use:
  "Whenever a user profile is updated in your system, the user.updated event is triggered."

If the generated text sounds robotic, you can use an AI humanizer to make it more natural. Then, give it a final review to remove unnecessary content, add your voice, and ensure accuracy.

Get Feedback Early

Don’t wait for the “final version” before asking for input. Documentation needs to be useful, and it’s better to get clarity early in the process. When you ask real humans for feedback on your documentation, you get a reality check before a customer spreads negative feedback about you.

Instead, test your docs in real-world conversations:

• Drop a how-to guide in your support team’s Slack and ask, “Would you send this to a user?”

• Ask a teammate or friend to follow your tutorial. Watch where they pause or get confused.

• Run it by sales or customer success, they know exactly where users get stuck in onboarding.

And if you're just a small team of two people, ask each other. Then ask each other's friends. You don’t need a formal process, just honest reactions from real people.

How Does Documentation Increase Sign-ups?

When a developer first arrives at your documentation page, they give it a few minutes to decide whether your tool is worth using, especially if they’re still exploring options.

If they’re required to use your tool for any reason, they’ll likely spend a day or two trying to figure things out. If they can’t find the right information, the frustration builds and often escalates to upper management. That’s when you risk not just losing a user, but losing a team or even a larger client.

Good documentation prevents that.

It is well-structured, speaks to users at all levels, and is easy to navigate. It keeps users on your page longer and encourages them to test your tool instead of bouncing to a competitor. If you also offer feedback channels or live support, users are more likely to reach out when they get stuck, and that support interaction can make all the difference.

Good documentation:

• Reduces support dependency, so users spend more time building and less time troubleshooting

• Lowers frustration, which signals maturity and product quality

• Builds trust by showing that your team has thought through user needs

• Helps users get something working quickly, which often turns into a sign-up

Making Complex Documentation Accessible

Writing good docs requires careful planning, collaboration, and a solid understanding of your users. Whether your developers are writing it or you're working with a technical copywriter, excellent documentation is rarely a solo job. It requires input from the people who developed the product and those who support its users daily.

When done right, your docs don’t just explain things – they make your product more straightforward to use, build trust with potential customers, and drive sign-ups.

Liked what you read? I help SaaS companies clarify their messaging and build authority through content. You can connect with me on LinkedIn.

docs.page is an open-source documentation tool that helps you create instant, fast, beautiful, and responsive documentation websites with minimal configuration. It is an open-source project developed by Invertase, a company known for creating developer tools and SDKs.

docs.page is designed to streamline the process of publishing documentation by sourcing content directly from public GitHub repositories.

Key Features:

• Zero configuration: you create a 'docs.json' file and a 'docs' directory. Inside the docs directory, you can create files using the .mdx extension, and docs.page will generate your documentation site.

• Customizable: docs.page allows you to add your logo, social links, theme, analytics, navigation, and more through a simple configuration file.

• Live previews: enables viewing of documentation for any branch, pull request, or specific commit, facilitating real-time collaboration and review.

• Hot reload: the Hot Reload feature provides real-time previews of documentation changes while editing Markdown (.mdx) files. This feature enhances the local development workflow, enabling instant updates without manual refreshes or rebuilds.

• GitHub bot integration: provides a GitHub bot that automatically generates URLs for pull request documentation previews.

• MDX support: you can write documentation in Markdown to utilize MDX, which enables you to use React components, such as tabs, Cards, Tweets, and Steps, directly within your Markdown file.

• Search functionality: integrates with DocSearch to offer full-text search capabilities within your documentation.

• Responsive resign: ensures that your documentation is accessible and visually appealing across a range of devices and screen sizes.

• Dark/light mode: offers theme customization to switch between dark and light modes.

• Code block highlighting: provides syntax highlighting and content copying features for code blocks.

Check out the code available in my GitHub repository.

Table of Contents:

• How Does docs.page Work?

• How to Enable Live Preview in docs.page

• How to Configure docs.page

• How to Use Pre-built Components in docs.page

• How to Diagnose Errors in docs.page

• How to Use Frontmatter

• How to Add Assets to Your Docs

• How to Publish Your Documentation Website

• How can you live preview your upcoming changes to your documentation website?

• Conclusion

How Does docs.page Work?

You can easily start creating your documentation page using the docs.page CLI. It helps you set up a local documentation project by running the following command:

pnpm dlx @docs.page/cli init docs.page

The command output appears as follows:

pnpm dlx @docs.page/cli init docs.page
? Are you sure you want to setup and install docs.page in /home/officialrajdeepsingh/medium/docs.page? yes
Files created:
 - docs.json: Configuration file for your documentation site
 - docs/index.mdx: The home page of your documentation site
 - docs/next-steps.mdx: A page to help you get started with docs.page

Initialization complete. To preview your documentation site, vist https://docs.page/preview in your browser.

After creating your project with the docs.page CLI, your project structure should appear as follows:

.
├── docs
│   ├── index.mdx
│   └── next-steps.mdx
└── docs.json

2 directories, 3 files

The docs folder contains the Markdown file for your documentation, and the docs.json file includes the configuration for your website, such as the header, sidebar, logo, theme, and other settings.

How to Enable Live Preview in docs.page

You can set up live preview of your local documentation in real-time in the browser – but it's a little different: you don't need to run any development commands on your laptop or machine.

To open the live preview of your local documentation, first visit https://docs.page and click the Local Preview button.

Next, select the documentation project on your laptop or machine and click the "Select Directory" button.

After clicking the "Select Directory" button, a new window will open depending on your operating system. Its UI may appear different. Then you need to select the project.

After selecting the folder, you will see the following alert message in the browser (“Let site view files?”). To view the live preview of your documentation website, click the "View files" button.

Now you can see a local live preview of the documentation website in the browser, and any changes you make locally will instantly reflect in the browser. By default, your documentation website should appear as follows:

Next, you’ll learn about configuring the Logo, Theme, Header, Social Links, Sidebar, SEO, search, and more on your docs. You’ll also learn how to use the pre-built components, Front Matter, and assets on docs.page, and finally, how to deploy your documentation website.

How to Configure docs.page

The docs.json file is the primary file for configuring your documentation. Below is a list of all available configuration options, which you can use to modify the logos, theme, analytics, and more on your docs.

Properties

• Basic properties

• Logo

• Theme

• Header

• Anchors

• Social Links

• SEO

• Variables

• Search

• Scripts

• Content

• Tabs

• Sidebar

There’s so much you can configure using docs.page – but in this tutorial, we’ll focus on some of the most important options:

• Properties

• Basic Properties

• Logo

• Theme

• Header

• Social Links

• SEO

• Search

• Tabs

• Sidebar

Basic Properties

docs.page includes basic common properties, such as name, description, and favicon, which is very important for SEO.

• name (string): The name of your project. It appears in the header and is used for things like SEO metadata.

• description (string): A summary of your project. This is used in meta tags and social preview images.

• favicon (string | Favicon object): Specifies the favicon shown in the browser tab. You can provide either a single string URL or use a Favicon object to define different icons for light and dark modes:

  • light (string): URL for the favicon in light mode.

  • dark (string): URL for the favicon in dark mode.

// docs.json
{
  "name": "Docs.page",
  "description": "Ship documentation, like you ship code",
  "favicon": "https://static.invertase.io/assets/docs.page/docs-page-logo.png",
   # or
  "favicon": {
    "light": "https://cdn-icons-png.flaticon.com/24/9664/9664027.png",
    "dark": "https://cdn-icons-png.flaticon.com/24/9643/9643115.png"
  }
}

Logo

Now it’s time to configure the logo for your documentation, which will appear in the header and be used for social preview images.

The minimum height of the logo must be 24px. You can provide URLS for both a light and a dark logo. If you only provide a light or dark logo, and it doesn't work, you may experience issues where your logo doesn't appear on the website when toggling the theme.

You can add the logo to the documentation in two ways:

• First way:

// docs.json
{
  "name": "My Docs",
  "logo": "https://cdn-icons-png.flaticon.com/24/2702/2702154.png",
}

• Second way:

// docs.json
{
  "name": "My Docs",
  "logo": {
    "light": "https://cdn-icons-png.flaticon.com/24/2702/2702154.png",
    "dark": "https://cdn-icons-png.flaticon.com/24/2702/2702172.png"
  }
}

Theme

Configuring the theme in your documentation is easy. If you don’t provide a theme, the default theme will be used in your documentation.

docs.page includes a theme property in docs.json, which holds a Theme object as its value with the properties defaultTheme, primary, primaryLight, backgroundLight, and backgroundDark.

• defaultTheme: You can select a theme, dark or light.

• primary: The primary colour is used for links, buttons, and other interactive elements.

• primaryLight: The primaryLight colour option is used in light mode. If your primary light option is not specified in the docs.json file, then the primary colour will be used.

• primaryDark: The primaryDark colour option is used in dark mode. If your primaryDark option is not specified in the docs.json file, then the primary color will be used.

• backgroundLight: The backgroundLight option is used to specify the background color of your documentation in light mode.

• backgroundDark: The backgroundDark option is used to specify the background color of your documentation in dark mode.

// docs.json
{
  "theme": {
    "defaultTheme": "dark",
    "primary": "#de40eb",
    "primaryLight": "#BFA213",
    "backgroundLight": "#e0cfff",
    "backgroundDark": "#00101f"
  },
}

Header

Configuring the header in your documentation includes the following properties: showName, showThemeToggle, showGitHubCard, and links.

• showName: The showName option displays the documentation name next to the logo in the header and defaults it is true.

• showThemeToggle: The showThemeToggle option displays the theme toggle button in the header (and defaults to true).

• showGitHubCard: The showGitHubCard option displays the GitHub card in the header and defaults to true.

• Links: The links option contains an array of Link objects to display a navigation in the header of your documentation.

// docs.json
{
  "header": {
    "showName": false,
    "showGitHubCard": false,
    "links": [
      {
        "title": "GitHub",
        "href": "https://github.com/officialrajdeepsingh/docs-page-demo"
      },
      {
        "title": "X",
        "href": "https://x.com/Official_R_deep"
      },
      {
        "title": "Linkedin",
        "href": "https://www.linkedin.com/in/officalrajdeepsingh"
      }
    ]
  }
}

Social Links

The social option contains an object of key-value pairs where the key represents the social platform and the value corresponds to the username or ID. Here’s how you can add them:

// docs.json
{
  "social": {
    "github": "officialrajdeepsingh/docs-page-demo",
    "x": "@Official_R_deep",
    "linkedin": "officalrajdeepsingh"
  }
}

SEO

The SEO option configures the SEO settings for your documentation. The noindex option tells search engines not to index your documentation, and it defaults to false.

// docs.json
{
  noindex: true
}

Search

To enable search functionality on your documentation site, you can integrate Algolia DocSearch by configuring the docsearch object in your docs.json file like this:

// docs.json
{
 "search": {
    "docsearch": {
      "appId": "YOUR_APP_ID",
      "apiKey": "YOUR_API_KEY",
      "indexName": "YOUR_INDEX_NAME"
    }
  }
}

Tabs

Tabs are an array of objects displayed at the top of your documentation website.

Properties

Each Tab object includes the following properties:

• id (string, required): A unique identifier for the tab.

• title (string, required): The text label displayed on the tab.

• href (string, required): The URL to navigate to when the tab is clicked.

• locale (string, optional): If set, this tab is displayed only when viewing documentation for the specified locale.

Here’s an example of a couple tabs:

{
  "tabs": [
    {
      "id": "root",
      "title": "Documentation",
      "href": "/"
    },
    {
      "id": "components",
      "title": "Components",
      "href": "/components"
    }
  ],
}

Sidebar

To display the sidebar on your website, you can configure or define it in the docs.json file your documentation, which will appear in the sidebar of your site.

Essentially, a sidebar is a list of links that appears on the side of your documentation. You can organize links using groups and pages by providing an array of sidebar objects.

Options:

• pages: The pages option takes a list of page links to display in the sidebar. It accepts the following options:

  • title (required): The title of the sidebar item.

  • href (required): The URL to link to when the sidebar item is clicked.

  • icon (optional): The icon to display next to the sidebar item.

• group (string): The title of the group under which the sidebar item will be displayed. If not provided, the item will appear at the top level of the sidebar.

• href (string): The URL the sidebar item will link to when clicked.

• icon (string): The name of the icon to display next to the sidebar item.

• tab (string): If set, the sidebar item will only be shown when a specific tab (matching the provided tab ID) is active.

// docs.json
{
"sidebar": [
    {
      "pages": [
        {
          "title": "Overview",
          "href": "/",
          "icon": "book"
        },
        {
          "title": "Configuration",
          "href": "/configuration",
          "icon": "gear"
        }
      ]
    },
    {
      "group": "Components",
      "icon": "grip",
      "pages": [
        {
          "title": "Getting Started",
          "href": "/components",
          "icon": "rocket"
        },
        {
          "title": "Accordion",
          "href": "/components/accordion",
          "icon": "square-caret-down"
        },
        {
          "title": "Callouts",
          "href": "/components/callouts",
          "icon": "bullhorn"
        },
        {
          "title": "Cards",
          "href": "/components/cards",
          "icon": "square-full"
        }
      ]
    }
  ]
}

If you want to learn more about this, check out the documentation here.

How to Use Pre-built Components in docs.page

docs.page comes with 15 pre-built components, so you don't need to import components into your MDX file. You can use them directly in your MDX file.

In the following example, I’m using the Info Callout component directly within the MDX file, without importing it.

// index.mdx
---
title: Welcome to docs.page!
description: Get started with docs.page
---

Welcome to docs.page! The init command you just ran has created a basic file struture in your project to help you get started.

## Walkthrough

### Configuration

In the root of your directory a new `docs.json` file has been created. This file is used to configure your documentation site. You can customize the name, description, and sidebar, theme, logos and more using this file.


<Info>Here's a basic example of what the file looks like: </Info>

How to Diagnose Errors in docs.page

If you encounter any errors on your documentation website, you can view all the errors by clicking the diagnostics button.

How to Use Frontmatter

Front matter is a block of YAML placed at the beginning of a Markdown file, enclosed between triple-dash (---) lines.

Frontmatter is a way to customise the metadata page directly within your Markdown files, and most importantly, frontmatter is used for SEO.

# docs/getting-started.mdx
---
title: Welcome to Awesome Project
description: Some awesome docs!
---

# Welcome!

Below is a list of some of the important frontmatter properties in docs.page, including their type and default values:

• title (string): The page’s title used in metadata, social cards, and displayed as the main heading.

• description (string): A summary of the page appears in metadata for SEO and link previews.

• image (string): URL of an asset used in social cards and (if enabled) shown at the top of the page.

• redirect (string): A URL to forward visitors to. When set, the page’s content is bypassed.

• showPageTitle (boolean): Toggle whether the page title appears as a heading at the top.

• showPageImage (boolean): Toggle whether the front-matter image is rendered at the top.

• noindex (boolean): If true, instructs search engines not to index the page.

Refer to the documentation for more detail and other frontmatter property information.

How to Add Assets to Your Docs

You can include assets, such as images and videos, in your documentation. You can add both remote and local assets.

Remote Assets

To add remote assets to your documentation, you can reference them directly in your markdown files.

For example, to include an image from a URL:

# getting-started.mdx
---
title: Welcome to get started
description: Some awesome docs!
---

# Welcome!

![Natural](https://cdn.pixabay.com/photo/2023/04/19/19/11/lake-7938396_960_720.jpg)

Local Assets

To use local assets in your documentation, create an assets folder inside the docs/ directory. Then, add images and videos to the assets folder and reference them in your Markdown files.

Check out the following to better understand:

docs/
  assets/
    natural.png
  index.mdx

Within your markdown file, you can reference the image using a relative path:

![Description](/assets/natural.png)

Different between Local vs Remote Assets

Local assets (PNG, JPG, PDF, and so on) are files stored within your project's public folder, while remote assets are files hosted on an external server. You can access your local assets using your domain URL.

![Natural](./assets/logo.png)

On the other hand, remote assets are stored on a different server (image hosting), as I mentioned. You can access remote assets with a full URL.

The best examples of remote assets include images from Unsplash, Pixabay, and Pexels that can be used directly in your MDX file.

![Natural](https://images.unsplash.com/photo-1728044849236-5e8a061e1895)

You can use remote and local assets based on your requirements – both have advantages and disadvantages. With remote assets, you can add an image directly in your mdx file. When using local assets, you add an image to the public folder and then reference it in your mdx file.

How to Publish Your Documentation Website

With docs.page, you can easily publish your documentation website. No configuration is required – once your documentation website is ready, you can just push your local code to a GitHub repository.

You can now access your documentation website immediately via the docs.page domain.

For example, if your GitHub repository is officialrajdeepsingh/docs-page-demo, your documentation will be available at https://docs.page/officialrajdeepsingh/docs-page-demo.

How to Live Preview Upcoming Changes to Your Docs Website

You can view previews of upcoming changes to your documentation before going public. As your documentation website grows, use the docs.page Github app – any pull request you create in your Github repository automatically generates a unique live preview URL.

To configure the docs page of the GitHub application in your repository, follow these steps:

1. Go to https://github.com/apps/docs-page

2. Click on the install button.

3. Select the GitHub account

4. Select All and single repository.

5. Click on the install button

6. Next, enter the password and OTP.

7. Now if your application is successful, install it in your repository.

Whenever you or another developer create a pull request in your repository, the docs page application creates live previews for you.

Conclusion

docs.page is a free, open-source project that allows you to create instant, fast, and beautiful documentation without requiring any configuration.

I think docs.page offers the best solution for documentation. You can easily set up and deploy your documentation website with the help of docs.page cloud service.

For now, it’s completely free to deploy a documentation website with a docs.page, and I hope it stays that way.

If docs.page ever decides to charge for their services, that could be troublesome. Hopefully, in that case, they’ll provide a clear guide on how to deploy your website on another cloud platform.

Here is another scenario: imagine purchasing an LG product, such as a smart TV without a guide on how to set it up and use the remote. Now you get the point.

The process of you trying to mount your fan or set up your smart TV will be a very frustrating and confusing one without any guidance. And most of the time, it’ll be hard to determine the full potential of the product you bought.

Now, keeping in mind the already painted scenarios, have you ever tried picking up a new programming language or using an unfamiliar API, only to find it confusing, and you felt completely overwhelmed at the beginning? Then you probably spent hours trying to piece things together, maybe via tutorials, but nothing seems to work perfectly due to the error messages you get…and you wonder if you’re doing the right thing.

But then you might have come across the product’s official documentation or maybe a properly written and well-structured guide (like this one you’re reading). Suddenly, everything clicks, you start writing code effortlessly or using the API with confidence. That’s it – the power of clear and concise documentation.

In this article, you will learn what an API is, how it works, what API documentation is all about, and how to create standard API documentation.

Let’s dive in.

Outline

1. What is an API?

   • How APIs Work

   • Types of APIs

2. What is API Documentation

3. Examples of API Documentation

4. Benefits of Clear API Documentation

5. Importance of a Clear API Documentation

6. Key Notes of API Documentation

7. Key Component of an API Documentation

8. Best Practices for Writing Concise API Documentation

9. Conclusion

Before we continue, let’s deviate a bit to learn what APIs are all about, how they work, and the types of APIs that are out there.

What is an API?

You might have heard the term API before, and you’re wondering what it’s all about. API stands for Application Programming Interface. An API acts as an interface between two programs that allows them to communicate. It is a mediator between the client (browsers/mobile application) and the server (backend).

How APIs Work

So now you know that an API acts as a bridge or middleman that allows two systems to communicate with each other. When working with APIs, you’ll come across two key terms: requests and responses. These two keywords are essential to understand because they form the core of how APIs work.

Think of requests and responses like what you use in a regular day-to-day conversation. It’s just like how you ask questions (request) and an answer is provided (response). Same thing happens with APIs, but in this case, its an interaction between software systems.

To explain better how an API works, let’s use a weather app or a stock market app. This should provide a clear view of what we are talking about.

When you open a weather app and want to check the current weather, the app doesn’t store the weather data itself. Instead, it sends a request through an API to the weather database server. When the request is sent, the API now interacts/communicates with the database server and retrieves the latest weather information, which is then sent back to the weather app as a response. Then this info is finally displayed to you.

This should be a smooth, fast, and continuous process and has to occur simultaneously for your app to run smoothly. This means that a request must be made first before a response can be received. You can’t get a response without making a request.

The same process occurs for the stock market app as well.

Types of APIs

APIs are categorised into two major types:

• By Use/Function

• By Access

Types of APIs by Use

• Web APIs: These are the most commonly used type of APIs and are also known as HTTP (Hypertext Transfer Protocol) APIs. This API enables communication over the internet with the use of HTTP. Examples of these APIs are REST APIs, GraphQL APIs, and so on.

• Library or Framework APIs: These are APIs provided by libraries or frameworks and are made use of by developers to build applications without having to build everything from scratch. Examples of this are React, JQuery, and so on.

• Operating System APIs: These are APIs built to allow systems/applications to communicate with operating systems. These APIs helps provide access to system-level resources, which is important for the application to function properly. Examples of these APIs are Android SDK, Windows API, and so on.

• Hardware APIs: These are APIs built to enable systems to communicate with the physical components of a hardware device. Examples of these APIs are Bluetooth APIs, Camera APIs, and so on.

• Database APIs: Just as the name states, they are APIs that allow applications to interact with the database. These APIs are essential and mostly used to store, retrieve, manage and update the database. Examples of these APIs are SQL-based APIs, NoSQL APIs, and so on.

Types of APIs by Access

• Open APIs: This can be seen as a public API and is also referred to as an external APIs. These are the types of APIs built and made available for anyone to use, therefore making them need little to no authorization and authentication. Based on the number of calls made to these APIs, some of them APIs are available for free while others are available at a specific cost (paid subscription).

• Partner APIs: These are types of APIs built and made available for just businesses that collaborate together. When this type of APIs are built, strong authentication and authorization process are put into consideration so as to avoid it from being accessed by the public.

• Internal APIs: The internal APIs can also be referred to as private APIs. These APIs are built and internally used by organization and are restricted from the public. These APIs are mostly used when there is communication between systems or Applications within the organization.

• Composite APIs: This is a type of API built in a way that it combines multiple API requests into a bundle and allows users to get one single response from different servers. This type of APIs is most commonly used when Devs needs to fetch data from multiple servers or data sources.

Now that we have broken down what APIs are, how they work, and their various types, let's move on to the main reason we’re here: learning about creating good API documentation.

What is API Documentation?

API documentation is also referred to as developer documentation. It is a well-written and organized guide or manual that explains how an API works. It’s designed to help developers (or even non-developers) understand what the API does, how to use it, and how to integrate it into their own projects.

By using API documentations, you can explore and take full advantage of everything an API has to offer. API documentation also aims at speeding up the development process and boosting the overall productivity of a product.

API documentation provides a detailed explanation of the complete functionality of the API, which can include:

• The most efficient way to use the API

• How to integrate the API with your project.

• The purpose of the API and the inputs to be passed for developers to make good use of it.

Examples of API Documentation

Here are some examples of API documentation to give you a better idea of what’s involved and what information these docs should provide.

Stripe API Docs

This is an example of a Web/HTTP API. Stripe is a payment processing tool, and the Stripe API documentation provides a clean, interactive, and developer-friendly guide on how to make use of the API for payment integrations.

React Docs

The React docs are an example of a library or framework API. They provide a detailed guide to how you can use React in building your web project

Android SDK

This is an example of an Operating System API. The Android SDK Documentation provides a detailed guide on how you can make use of the Android SDK API to build your Android app.

Web Bluetooth API

This is an example of a hardware API. The Web Bluetooth API Docs provide a detailed guide on how to make use of the API to connect and interact with Bluetooth low energy peripherals.

PostgreSQL API

This is an example of a Database API. The PostgreSQL API Docs provide developers with full details on what the API is all about, how they can effortlessly connect it with their application, and also the roadblocks they can encounter while using the API and how to overcome them.

Benefits of Clear API Documentation

Enhances the Developer Experience

Great API documentation makes a developer’s life much easier. It clearly explains what the API does, how it works, and how to use it – all of which help developers get up to speed quickly.

Instead of wasting time figuring things out or getting stuck, they can focus on building. It reduces frustration, boosts productivity, and even makes it easier to collaborate with teammates.

Reduces the Learning Curve

Good API documentation helps reduce the learning curve for developers trying to use the API. This, in turn, leads to faster onboarding, saves time and money, and encourages higher adoption rates.

Easy to Maintain

Good API documentation makes it easier to maintain both the API and any application the API is used in. Up-to-date docs help developers understand changes, fix bugs, and update features in their application with confidence.

Provides Visibility for Your Product

Good API documentation increases the visibility of your product and encourages frequent use by making it easier for developers to understand and integrate it. It also promotes third-party integration, helping your product reach a wider audience.

Key Components of API Documentation

There are many components that make up a good API documentation. In this section, we will walk through a real-world example of properly prepared API documentation: the Spotify Web API.

Overview/Description and Uses of the API

This is the very first stage in writing good API documentation. This section explains to users what the API is all about and also has information about the type of resources it provides.

The overview section is usually short, perhaps 3-4 sentences, and it describes what the API is does, the available resources, its endpoints, and the methods attached to each endpoint. This helps bring you up to speed as to whether that particular API provides what you need to complete your project.

As you can see, the Spotify API’s description explains how it helps you create applications that “can interact with Spotify’s streaming service, such as retrieving content metadata, creating and managing playlists, or controlling playback.”

Endpoints

Endpoints are an important component in API documentation. Developers use them to communicate with other servers. They’re also used for data transfers. An Endpoint is referred to as the “touch point” in the communication channel between two servers.

When documenting an endpoint, it’s important to take note of the various components of the endpoints, as this increases the quality of your API documentation. The components of an endpoint include its name, description, url, methods, parameters, and so on.

For example, if you want to get the details of a user’s top artist, here’s how the endpoint looks:

GET https://api.spotify.com/v1/me/top/artists

Remember, we previously mentioned the key components that make up an API endpoint, such as the name, description, URL, and HTTP method. Let's take the Spotify endpoint URL above to see how these components are presented:

• Name: Get User's Top Artists

• Description: Retrieves the current user's most listened-to artists.

• URL: https://api.spotify.com/v1/me/top/artists

• Method: GET

This endpoint demonstrates how a well-documented API provides all the necessary details a developer needs to understand and use it effectively.

Response:

{
  "rank": 1,
  "name": "Eminem",
 },

{
  "rank": 2,
  "name": "NF",
 },

{
  "rank": 3,
  "name": "Adele",
 },

Now the code above indicates the response I should get from my initial request and it is displayed in a JSON format.

Authorization and Authentication:

Both authorization and authentication are important tools used for checking the access that’s been given to sensitive data.

APIs receive thousands of responses and handle huge amounts of data. Authentication and Authorization are ways to ensure that your API data and your users are safe and secure from hackers.

Note that authentication and authorization are two different concepts. Authentication is mainly all about verifying the identity of someone who wants to use your API. Authorization, on the other hand, describes the level of access that an already verified user has when interacting with the API.

There are three major types of API Authentication. Each type is used at different stages or levels, but in some scenarios, no authentication is used at all.

• Basic Authentication: This is the type of API auth that is usually used for testing internal APIs. It’s not recommended for publicly used APIs because it’s not fully secure. This API sends a username and password with every API call made to the client.

• Key Authentication: In this type of auth, the client generates and sends a very long key. The API key is a long string that contains unique authorization tokens. This type of auth is more secure than the basic auth – but if the key is leaked, anyone can access the API until it’s revoked. Note: This type of Authentication is used for light applications.

• OAuth Authentication: OAuth is the most common and more secure token-based type of authentication. In this type of authentication, instead of sending a username and password, an authorization is first requested, which is approved by the user. After the user approves the request, a token is generated which can be used to make an API request. This method is secure, and the tokens generated have an expiration time as well.

Let’s look at an example from the Spotify API.

Spotify uses OAuth 2.0 for authentication and access control. To use most of Spotify’s Web API endpoints, you must first authenticate your application and obtain permission from the user:

GET https://accounts.spotify.com/authorize

Here are the key details of the Authorization endpoint:

• Name: Authorization

• Description: Initiates the OAuth 2.0 flow to authorize users and allow your application to access Spotify data on their behalf.

• URL: https://accounts.spotify.com/authorize

• Method: GET

Parameters and Headers:

Parameters are the variable part of a resource and comprise a name, value, and description. Some parameters are required and are used in making API calls, while some are just optional.

When writing an API documentation, you should list out all the parameters and descriptions alongside each parameter. It’s also a good idea to specify why such a parameter is needed and state if it is required or optional in the documentation.

Headers, on the other hand, are similar to parameters. They have key-value pairs and are used to send additional information (metadata) about a request to the server. If there are any headers used in your API, then it is important you include them when documenting the API.

As you can see in the image above, we have some Body Parameters and Header Parameters. For body parameters, there’s grant_type (which is required), code (also required), and redirect_uri (also required). You can also see that they have descriptions of the value listed.

For header parameters, we have Authorization (required) and Content-Type (also required), again with descriptions of their values.

Error Handling Codes and Troubleshooting Guidance:

Errors are inevitable, they’ll always occur despite how careful you are. That’s why good API documentation should include guidance to help developers recover quickly when things go wrong.

Your documentation should provide a section that;

• Suggest possible fixes or troubleshooting tips for some specific errors.

• Include sample error response codes and logs, which help in debugging.

When it comes to API calls, two key components to understand are the request and the response. When an API call is made, a request is sent to the server, and a response is returned. This response includes a status code and, if applicable, an error code and both are essential for understanding what happened during the request.

For example, there are situations when you make an API call and the response you get is a code 404, which means that the request you made was not found. But when things go smoothly, you should see a code 200, which means your request was successful.

Here is what this section looks like:

{
  "error": {
    "status": 404,
    "message": "Not Found"
  }
}

By properly documenting these status and error codes with their explanations, developers can easily identify issues and take appropriate actions to solving it those issues.

Here are some common Response Code Statuses and what they mean:

Response Code Status:

The table above shows some of the most common code response statuses you’ll come across when using an API and its description.

Best Practices for Writing Concise API Documentation

Here are some best practices that can help guide you while writing API documentation:

1. You want to make sure users clearly understand what the API is, how they can use it, and the limits of use for the API.

2. Know your target audience and focus on what they need most to get started with the API docs.

3. Always stick to the essential information and use clear and consistent language.

4. Structure your documentation properly and make it standard.

5. Examples are important. Always use them in your documentation and make sure you clearly explain them.

6. Avoid repetition in your documentation.

7. Always document your error codes clearly. It’s recommended that you put them in tabular format.

8. Always provide a link to outsourced files in situations when more details are needed. This helps keep your documentation short and on point.

9. Review and regularly update the documentation.

10. Incorporate user feedback for continuous improvement.

Conclusion

API documentation has become a critical component in today's technology landscape. Clear and concise documentation is not just helpful – it’s essential. It often determines whether an API succeeds in the tech ecosystem and whether developers can fully leverage its power.

This is a call to action for developers, organizations, and technical writers: prioritize high-quality, well-structured API documentation. The clarity of your documentation directly impacts the usability, adoption, and long-term success of your product in the industry.

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.

This structured document is called an OpenAPI specification (OpenAPI Spec or OAS).

An OpenAPI spec is a format for describing APIs. It's a blueprint that outlines everything about how an API works — what endpoints are available, what data you can send or receive, and what responses to expect.

This means that a well-written OAS file means well-written API reference documentation.

When writing this file, there are some parts that can get a bit complicated. For example, you might have to document a single endpoint with different methods or sometimes duplicate endpoints.

I encountered and documented both of those use cases. So, in this article, I'll show you how you can do the same. We'll go through each use case with sample OpenAPI specs, and at the end, I'll leave you with some useful tips for documenting your OpenAPI spec files.

Table of Contents

• Prerequisites

• Setting the Foundation

• Use Case 1: Duplicate Endpoints

• Use Case 2: How to Document Multiple HTTP Methods

• API Documentation Tips

  • Use Markdown in OpenAPI

  • Use the operationId Field

  • Use $ref for Reusable Components

• Conclusion

Prerequisites

There are a few things you need to know to follow along with the use cases below. These include:

1. A basic knowledge of APIs and API documentation: Familiarity with API terminology and structure (for example, endpoints, methods, request/response structure) is essential to understand how an OpenAPI Specification (OAS) document functions.

2. Familiarity with OpenAPI Specification: Basic understanding of OAS, including its purpose, structure, and so on.

3. Access to Swagger or other OpenAPI documentation tools: You need tools like the Swagger Editor or RapiDoc, which will allow you to test and view the OpenAPI files visually.

Setting the Foundation

In both programming and in life, if you can determine that something is "complex," this means that there's also a simplistic-regular way it can be as well. And that's the same for an OAS file.

When creating your spec file, you might not always encounter the use cases we'll address shortly. That's why it’s useful to know what a conventional spec file looks like.

An OpenAPI spec is a human and machine-readable file written in JSON or YAML. Below is an example of an OAS file structure in YAML format:

paths:
  /users:
    get:
      summary: Get a list of users
      responses:
        '200':
          description: A list of users.
  /users/{userId}:
    get:
      summary: Get details for a single user
      parameters:
 - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Details of a single user.
  /orders:
    get:
      summary: Get a list of orders
      responses:
        '200':
          description: A list of orders.

Here's a brief breakdown of this OAS file structure:

1. Paths: The paths section allows you to list each endpoint or URL that you can interact with in this API. Each path, such as /users or /orders, shows what type of data you can get or send to that URL.

2. Operations: Under each path, there's a method or operation, like GET, which tells us what we can do with that endpoint. In this example, each path uses GET, which means you request information.

3. Summary: Each operation has a summary — a short description explaining what the endpoint does, like "Get a list of users" or "Get details for a single user."

4. Parameters: For paths that include placeholders, like /users/{userId}, you'll see a parameters section explaining what details are required.

5. Responses: Each operation includes a responses section, which lists the possible API responses.

NOTE: This is not a complete OAS file. I omitted some preceding information for the purpose of this explanation.

Now, let’s dive into the more complex scenarios.

Use Case 1: Duplicate Endpoints

During the development of an API, you may create a single endpoint with multiple variations. Depending on the use case, you might want that endpoint to accept multiple data formats or specific parameters.

When you encounter such scenarios and want to document the API reference using an OpenAPI spec, you won't be able to replicate it exactly how it is in the Postman collection (or any other development environment).

If you did try, you'll get this error:

The workaround for this problem is to consolidate these multiple variations under a single path definition by grouping the different requests and responses as examples.

In the example below, you have an API that has an endpoint for managing session registration at a conference. This endpoint has various requests and responses based on registration type (for example, Speaker, Attendee, or VIP).

In a Postman collection, you can have each of these endpoints in a separate folder for easy identification and testing.

But when documenting your spec file, it should look like this:

openapi: 3.0.0
info:
  title: Conference Events API
  description: API to manage event registrations for conferences
  version: 1.0.0
paths:
  /register-session:
    post:
      tags:
        - Registration
      summary: Register for a conference session
      description: Register a user for a specific session based on their role, with details provided for each registration type.
      operationId: registerSession
      requestBody:
        description: Registers a user for a session at the conference. It accepts different formats for attendance, speaker, or VIP registrations.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionRegistration'
            examples:
              Attendee:
                summary: Register as an Attendee
                value:
                  userType: Attendee
                  userId: 789
                  sessionId: 1234
                  preferences:
                    seating: General
                    accessLevel: Basic
              Speaker:
                summary: Register as a Speaker
                value:
                  userType: Speaker
                  userId: 456
                  sessionId: 1234
                  preferences:
                    seating: VIP
                    accessLevel: Full
                    presentationEquipment: Projector
              VIP:
                summary: Register as VIP
                value:
                  userType: VIP
                  userId: 123
                  sessionId: 1234
                  preferences:
                    seating: Front Row
                    accessLevel: Full
                    exclusiveAccess: true
      responses:
        '200':
          description: Successful registration for Attendee, Speaker, or VIP
          content:
            application/json:
              schema:
                type: object
                properties:
                  registrationId:
                    type: string
                  success:
                    type: boolean
              examples:
                Attendee:
                  summary: Response for Attendee registration
                  value:
                    registrationId: att-456def
                    success: true
                Speaker:
                  summary: Response for Speaker registration
                  value:
                    registrationId: spk-123abc
                    success: true
                VIP:
                  summary: Response for VIP registration
                  value:
                    registrationId: vip-789ghi
                    success: true
components:
  schemas:
    SessionRegistration:
      type: object
      properties:
        userType:
          type: string
          description: Type of user registering (e.g., Attendee, Speaker, VIP)
        userId:
          type: integer
          description: Unique ID of the user
        sessionId:
          type: integer
          description: Unique ID of the session to register for
        preferences:
          type: object
          properties:
            seating:
              type: string
              description: Seating preference (e.g., General, VIP, Front Row)
            accessLevel:
              type: string
              description: Access level granted (e.g., Basic, Full)
            presentationEquipment:
              type: string
              description: Required equipment for Speakers (only applicable to Speaker)
            exclusiveAccess:
              type: boolean
              description: Exclusive access for VIP users

In this file, you have a single POST /register-session path that captures all registration types without duplicating endpoints.

Here's a visual representation of this OAS file using the Swagger editor:

Use Case 2: How to Document Multiple HTTP Methods

Another use case you may encounter happens when you have the same endpoint but different HTTP methods.

This usually comes up because each method serves a different purpose, even though they share the same path.

For example, a GET method retrieves information about a resource, like viewing a user's registration details for a conference session.

On the other hand, a PATCH method updates specific fields for that same user registration, like updating their seat preference.

Since both the GET and PATCH methods relate to the same resource (/register-session in our example), the way around this is to group them under the same path. This way, you'll be documenting two separate methods for a single path.

In OpenAPI, each combination of a path and method is called an "operation". Grouping operations that share the same path helps maintain clearer and more structured documents.

Using the conference events API example, this is what your OAS file should look like:

openapi: 3.0.0
info:
  title: Conference Events API
  description: API to manage event registrations for conferences
  version: 1.0.0
paths:
  /register-session:
    get:
      tags:
        - Registration
      summary: Retrieve a registration for a conference session
      description: Fetch details for a specific user's registration, like seat assignment and access level.
      operationId: getSessionRegistration
      parameters:
        - in: query
          name: userId
          schema:
            type: integer
          required: true
          description: The ID of the user whose registration you want to retrieve.
      responses:
        '200':
          description: Registration details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionRegistration'
              example:
                userId: 789
                sessionId: 1234
                preferences:
                  seating: General
                  accessLevel: Basic
                  exclusiveAccess: false

    patch:
      tags:
        - Registration
      summary: Update a registration for a conference session
      description: Update specific fields for a user's session registration, such as seating or access level.
      operationId: updateSessionRegistration
      requestBody:
        description: Allows updating fields for a specific session registration.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSessionPreferences'
            example:
              userId: 789
              preferences:
                seating: VIP
                accessLevel: Full
                exclusiveAccess: true
      responses:
        '200':
          description: Registration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              example:
                success: true
                message: "Registration updated successfully."
components:
  schemas:
    SessionRegistration:
      type: object
      properties:
        userId:
          type: integer
          description: Unique ID of the user
        sessionId:
          type: integer
          description: Unique ID of the session
        preferences:
          type: object
          properties:
            seating:
              type: string
              description: Seating preference (e.g., General, VIP, Front Row)
            accessLevel:
              type: string
              description: Access level granted (e.g., Basic, Full)
            exclusiveAccess:
              type: boolean
              description: Exclusive access granted to certain users

    UpdateSessionPreferences:
      type: object
      properties:
        userId:
          type: integer
          description: Unique ID of the user
        preferences:
          type: object
          properties:
            seating:
              type: string
              description: New seating preference (e.g., VIP)
            accessLevel:
              type: string
              description: Updated access level (e.g., Full)
            exclusiveAccess:
              type: boolean
              description: Updated access preference (e.g., true or false)

In this file, you have a single /register-session path with multiple methods. We define just one path, /register-session, and list the GET and PATCH methods under it. This keeps the spec clean, reduces duplication, and shows that these methods relate to the same resource.

Here's a visual representation of this OAS file using the Swagger editor:

API Documentation Tips

While working with OpenAPI specifications, there are some useful tricks and tips that can make your OAS file more readable and maintainable.

Use Markdown in OpenAPI

OpenAPI specifications allow the use of Markdown in the description field. The version of Markdown used in OAS is called CommonMark, the same version used in GitHub.

Markdown formatting allows you to make text more visually engaging and organized. You can add formatting such as headers, lists, code blocks, bold, italics, and so on, which can make your documentation easier to scan and more accessible for readers.

For example, if you need to emphasize certain parts of an endpoint's purpose or highlight important details, Markdown lets you do it naturally.

You can add Markdown directly into any description field in the OpenAPI file, like this:

paths:
  /register-session:
    get:
      description: |
        ## Retrieve Session Registration
       Retrieves the registration details for a specific user.  
       - **Note:** This data includes seat assignment and access level.  
       - Example of JSON response: `{"userId": 789, "sessionId": 1234, "seating": "General"}`
      responses:
        '200':
          description: Registration details retrieved successfully

When deployed to supported documentation platforms like RapiDoc or ReadMe, this will render beautifully with all your Markdown styling intact.

Here's a deployed version of this example in Readme:

Use the operationId Field

The operationId field is an optional field in OpenAPI specs that assigns a unique name to each API operation.

It is an identifier that you can use to call specific methods when integrating with SDKs or when linking between parts of your documentation.

By effectively using the operationId, you make it much easier for developers to reference specific actions in the API, which is especially helpful when the API is complex or has multiple endpoints.

Place the operationId inside each HTTP method block to give it a unique identifier. For instance:

paths:
  /register-session:
    get:
      operationId: getSessionRegistration
      description: Retrieve a registration for a conference session
      responses:
        '200':
          description: Successfully retrieved the registration
    patch:
      operationId: updateSessionRegistration
      description: Update a registration for a conference session
      responses:
        '200':
          description: Registration updated successfully

With the operationId, developers can directly refer to getSessionRegistration or updateSessionRegistration as function calls in code or API clients.

Use $ref for Reusable Components

The $ref keyword in OpenAPI lets you create and reuse components across your spec file. This technique is especially helpful when you have similar request bodies, responses, or parameters repeated in multiple endpoints.

By defining components in a single place and referencing them as needed, you avoid redundancy, reduce errors, and facilitate updates.

So, instead of updating the same parameter across multiple locations, you update it once in the reusable component, and every endpoint using it gets the update.

To use it, first define the reusable component in the components section of your OpenAPI file, then reference it elsewhere using $ref:

components:
  schemas:
    RegistrationDetails:
      type: object
      properties:
        userId:
          type: integer
        sessionId:
          type: integer
        seating:
          type: string
paths:
  /register-session:
    post:
      summary: Register for a session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegistrationDetails'
      responses:
        '201':
          description: Successfully registered for the session

In this file, RegistrationDetails is defined once and is referenced using the $ref keyword in the /register-session operation.

Conclusion

In this article, you learned how to resolve some complex use cases you might encounter when documenting your API reference using an OpenAPI specification. We went through what to do when you have a single endpoint with multiple methods or duplicate endpoints.

Creating your API reference without an OpenAPI spec file is a manual approach that can become redundant if you have to replicate it across various platforms. But by relying on the tips from the article, you're sure to create better, more efficient, and more reusable OpenAPI specifications. And these, in turn, will lead to better API documentation.

As projects grow and evolve, managing documentation across various formats—whether it’s markdown, HTML, or PDF for offline use—can become a time-consuming and error-prone task.

Pandoc is a powerful tool that allows you to convert documentation between formats seamlessly.

Still, even with Pandoc, manually converting files for every update can become a bottleneck in large projects or teams where documentation is frequently updated.

In this article, I’ll guide you through setting up shell scripts, using Makefiles, and integrating Pandoc into CI/CD pipelines to streamline your workflow and keep your documentation up-to-date with minimal effort.

Table of Contents

• Why Automate Documentation Conversion?

• How to Automate Pandoc using Shell Scripts

• Basic Shell Script for Pandoc Conversion

• Customizing the Script for Several Files

• Automating with Makefiles

• A Makefile for Pandoc Conversions

• Defining Dependencies in Makefiles

• Why Use Makefiles for Pandoc Automation?

• How to Integrate Pandoc with CI/CD Pipelines

• Example: Setting Up Pandoc with GitHub Actions

• Triggering on Documentation Updates

• Adapting for GitLab CI or Jenkins

• Advanced Automation Techniques

• Automating with Cron Jobs

• Ensuring Consistency with Docker

• Combining Tools for Efficiency

• Conclusion

Why Automate Documentation Conversion?

Manually converting documentation between formats in large projects can become a daunting task.

Whether you're generating HTML, PDF, or DOCX versions from the same source, repeating this process for every update leads to various challenges:

• Time-Consuming: Running manual commands to convert documentation every time you make a change eats into valuable development time when updates happen often.

• Prone to Errors: The manual process increases the likelihood of mistakes, such as using incorrect commands, missing steps, or generating outdated versions of your documentation. These inconsistencies can confuse both developers and end-users.

• Difficult to Scale: As projects grow in size, managing documents across different formats without automation can become unmanageable. Teams working in parallel may struggle to keep documentation synchronized, leading to mismatches between formats.

By automating the conversion process with tools like Pandoc, you can overcome these challenges and enjoy a range of benefits:

• Consistency: Automation ensures that all versions of your documentation are always up-to-date and accurate. No matter the number of formats you're generating, the process remains standardized.

• Efficiency: Automated workflows free up time by handling repetitive tasks in the background, allowing teams to focus on development rather than manually managing documentation updates.

• Scalability: With automation, it’s straightforward to scale documentation efforts as your project grows. Whether you're maintaining a single document or an entire library of resources, automation makes sure everything stays synchronized with minimal effort.

The next section explores how to automate the conversion process.

How to Automate Pandoc using Shell Scripts

By using shell scripts, you can streamline the process of running PanDoc commands, saving time and reducing the risk of errors associated with manual command execution.

Basic Shell Script for PanDoc Conversion

To get started, we’ll create a shell script that converts a single Markdown file into various formats.

For instance, here’s a script that converts input.md into HTML and PDF:

#!/bin/bash

# Convert input.md to HTML and PDF
pandoc input.md -o output.html
pandoc input.md -o output.pdf

echo "Conversion complete!"

In the above script:

• The #!/bin/bash line indicates that the script should be run using the Bash shell.

• The pandoc commands convert the input.md file into output.html and output.pdf.

• The echo command confirms that the conversion process is complete.

Customizing the Script for Several Files

If you want to convert all Markdown files in a directory, you can customize your script to process several files at once.

For instance, here’s a script that converts input.md into HTML and PDF:

#!/bin/bash

# Go through all the Markdown files present in the current directory
for file in *.md; do
  # Convert each Markdown file to PDF
  pandoc "$file" -o "${file%.md}.pdf"
done

echo "All conversions complete!"

In this script:

• The for loop iterates over each .md file in the current directory.

• The pandoc command converts each Markdown file to a PDF, preserving the original filename but changing the extension to .pdf with the ${file%.md}.pdf syntax.

• The final echo confirms that all conversions are complete.

Adding Error Handling and Complex Logic

To enhance your script's robustness, you can add error handling and extra logic.

For instance, perhaps you want to make sure that Pandoc is installed before proceeding, and handle cases where the input file may be missing.

The script will be as follows:

#!/bin/bash

# Check if Pandoc is installed
if ! command -v pandoc &> /dev/null; then
  echo "Pandoc is not installed. Please install it and try again."
  exit 1
fi

# Go through all the Markdown files present in the current directory
for file in *.md; do
  if [ -e "$file" ]; then
    # Convert each Markdown file to PDF
    pandoc "$file" -o "${file%.md}.pdf"
    echo "Converted $file to PDF."
  else
    echo "No Markdown files found."
  fi
done

echo "All conversions complete!"

In this enhanced script:

• The if ! command -v pandoc &> /dev/null; then line checks whether Pandoc is installed.

• The if [ -e "$file" ]; then statement checks if each Markdown file exists before attempting to convert it.

• An informative message is printed after each successful conversion, providing feedback on the process.

As your project grows in complexity, relying solely on shell scripts for automation can become difficult to manage when dealing with lots of files and frequent updates.

This is where Makefiles come in handy.

Automating with Makefiles

A Makefile is a special file that defines rules and commands for automating tasks in a project.

It’s widely used by developers to compile code, but developers can also leverage it for non-compilation tasks, such as converting documentation formats with Pandoc.

A Makefile for Pandoc Conversions

Here’s an example of how you can create a Makefile to automate Pandoc conversions:

all: html pdf

html:
    pandoc input.md -o output.html

pdf:
    pandoc input.md -o output.pdf

In this Makefile:

• all is the default target. When you run make without specifying a target, it will run the html and pdf targets sequentially.

• The html target runs a PanDoc command to convert input.md into output.html.

• The pdf target runs a PanDoc command to convert input.md into output.pdf.

To use this Makefile, run the following command in your terminal:

codemake

This will execute both the html and pdf targets, converting the Markdown file into both formats.

Defining Dependencies in Makefiles

One of the major strengths of Makefiles is their ability to handle dependencies.

In the context of documentation conversion, you can specify which files to update when you detect changes in the source file.

Let’s look at an example:

output.html: input.md
    pandoc input.md -o output.html

output.pdf: input.md
    pandoc input.md -o output.pdf

In this Makefile:

• The output.html and output.pdf files depend on input.md.

• If you run make output.html or make output.pdf, Pandoc will regenerate the corresponding file if you update input.md after the last time you created the output file.

This ensures that Pandoc converts the files that have changed, saving time when working on large documentation projects.

Why Use Makefiles for Pandoc Automation?

Makefiles offer several advantages for automating Pandoc conversions in larger projects:

• Efficiency: Makefiles rebuild what’s necessary, meaning you won’t waste time converting files that haven’t changed.

• Simplicity: Once set up, running make simplifies the conversion process to a single command, making it easier for teams to maintain consistent documentation workflows.

• Scalability: As your project grows, you can add more targets and dependencies to the Makefile, automating everything from documentation to more complex build processes.

Makefiles are an excellent option for automating documentation conversions, when combined with Pandoc for multi-format outputs.

They help ensure that your workflow is efficient and your documentation remains up-to-date.

As modern development practices increasingly rely on Continuous Integration and Continuous Deployment (CI/CD), automating routine tasks such as documentation generation becomes essential.

Integrating Pandoc into your CI/CD pipelines allows for seamless documentation conversion and updates, ensuring that your docs are always up-to-date without manual intervention.

By automating this process, you can focus on coding and building, while your pipeline handles the conversion and distribution of your project documentation. Let’s explore how to set up Pandoc in a CI/CD pipeline to streamline your documentation workflows.

How to Integrate Pandoc with CI/CD Pipelines

Automating documentation generation within your CI/CD pipeline brings significant benefits, including consistency, efficiency, and hands-off updates.

Whether you’re using GitHub Actions, GitLab CI, Jenkins, or another automation tool, integrating Pandoc ensures that documentation gets generated and distributed whenever changes occur.

This approach reduces the risk of outdated or inconsistent documentation.

Example: Setting Up Pandoc with GitHub Actions

Let’s walk through a clear example of how you can use GitHub Actions to automate the process of generating documentation with Pandoc.

Below is a basic workflow that converts a Markdown file (*.md) into a PDF whenever code gets pushed to the repository.

name: Generate Documentation

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # Step 1: Checkout code from the repository
      - name: Checkout code
        uses: actions/checkout@v2

      # Step 2: Install Pandoc
      - name: Install Pandoc
        run: sudo apt-get install pandoc

      # Step 3: Convert Markdown to PDF
      - name: Convert Markdown to PDF
        run: pandoc input.md -o output.pdf

      # Step 4: Upload the generated PDF as an artifact
      - name: Upload Documentation
        uses: actions/upload-artifact@v2
        with:
          name: documentation
          path: output.pdf

Here’s a breakdown of each step:

• Checkout Code: The actions/checkout@v2 action retrieves the latest code from your repository.

• Install Pandoc: This step installs Pandoc on the runner (in this case, an Ubuntu machine) so that it can gets used for the documentation conversion.

• Convert Markdown to PDF: The PanDoc command converts the input.md file into output.pdf.

• Upload Documentation: This step saves the generated PDF as an artifact in the CI/CD pipeline, making it downloadable or accessible later

Triggering on Documentation Updates

You can configure your CI/CD pipeline to trigger when documentation updates occur, for example, when changes get pushed to a docs branch:

on:
  push:
    branches:
      - docs

This setup ensures that your documentation gets regenerated when changes are specifically made to the documentation branch, reducing unnecessary rebuilds.

Adapting for GitLab CI or Jenkins

While the above example uses GitHub Actions, the same principles work on other CI/CD systems like GitLab CI or Jenkins.

For instance, in GitLab CI, you could define a .gitlab-ci.yml file that follows similar steps to check out the code, install Pandoc, convert the files, and store the resulting documentation.

Integrating Pandoc into your CI/CD pipeline offers a reliable way to automate your documentation workflows, ensuring that your project docs are always current, accurate, and accessible.

Advanced Automation Techniques

When your project reaches a stage where documentation needs to be generated frequently or across multiple environments, it’s essential to extend your automation strategy to maintain consistency and reliability.

Automating with Cron Jobs

For projects where documentation updates occur frequently, but not always due to code pushes or commits, you can automate the process using cron jobs.

Cron allows you to schedule tasks at specific intervals, meaning your documentation can automatically get updated at set times without needing manual input.

For example, setting up a cron job to run every day at midnight to convert Markdown files to PDFs:

0 0 * * * /path/to/pandoc /path/to/input.md -o /path/to/output.pdf

With this cron job in place, Pandoc will automatically convert your Markdown files to PDFs at the specified time, ensuring that your documentation remains up-to-date without manual intervention.

Ensuring Consistency with Docker

When working in a team or across various systems, ensuring that Pandoc runs consistently in different environments can be challenging.

Docker provides a solution to this by allowing you to package Pandoc and all its dependencies in a container, ensuring that the same setup gets used everywhere.

This is useful in CI/CD pipelines, where different environments (like local machines, staging, and production servers) can have different configurations.

You can use the official Pandoc Docker image to simplify the setup process:

docker run --rm -v $(pwd):/data pandoc/core:latest input.md -o output.pdf

This command runs Pandoc inside a Docker container, using the latest version of Pandoc, and mounts your current directory to the container’s /data directory.

By doing this, you ensure that no matter where the pipeline runs, the conversion will work the same way every time.

Combining Tools for Efficiency

By combining tools like cron jobs and Docker, you can set up an advanced automation pipeline that ensures:

• Scheduled updates: Cron jobs trigger documentation generation at regular intervals.

• Consistency across environments: Docker ensures that Pandoc and its dependencies are the same on every machine.

• Reliability: Together, these tools help ensure that your documentation is always accurate, no matter where or when it’s generated.

These advanced techniques allow you to further streamline your documentation workflows, improving both efficiency and reliability as your project grows.

Conclusion

Automating documentation conversion with Pandoc not only saves time but also ensures consistency and scalability as your project grows.

Whether you’re managing small or large projects, these techniques enable you to focus on coding and building, knowing that your documentation is automatically up-to-date and ready for distribution.

By embracing automation, you streamline your development process and enhance collaboration across teams, ensuring that your documentation evolves as efficiently as your code.

Now it’s time to apply these tools to your projects and enjoy the benefits of a fully automated documentation pipeline.

Let’s stay in touch:

• Connect with me on LinkedIn. I post regularly, so following me is a great idea.

• Follow me on X

Feel free to reach out through the channels above if you have any questions. I will be happy to help.

This is why documentation tools like Docusaurus are great for helping you create visually stunning documentation sites in abo 5 minutes.

In this tutorial, I'll show you how to build a documentation site using React and Docusaurus.

If you are new to Docusaurus, you are probably wondering, “why React?, why not any other framework like Next.js?”, Don’t worry – I’ll also answer this question in this guide.

Table of Contents

• Prerequisites

• What is Docusaurus?

• Getting Started and Installation

  • Project structure

• How to Start Your Docusaurus Website

• How to Create Documentation (Overview)

• MDX and React Components

  • Tabs

  • Alerts or Admonitions

  • Code blocks

• Docusaurus Blog

• Custom Pages

• Styling in Docusaurus

• Deployment

• Conclusion

Prerequisites

To follow along with this guide, you should have:

• Node.js version 18.0 or above installed

• Basic knowledge of React and Markdown

• IDE (preferably VSCode)

What is Docusaurus?

Docusaurus was released by the Meta Open Source team in 2017 to help devs build, deploy, and maintain documentation websites easily and quickly. The project’s other goal was to improve the speed of both developers and end users using the PRPL pattern.

Some of its cool features include search and localization, powered by Algolia (search) and Crowdin (language support and internationalization).

Now, let’s talk about why we’re using React for this tutorial. Well, Docusaurus is built on top of React, which makes it easy to customize the website. Also, Docusaurus supports Markdown and MDX (which lets you use React JSX in your markdown content).

As a technical writer myself, I love that this tool supports Markdown, which I'm quite familiar with. It allows me to focus on creating helpful documentation without worrying about converting the text to other text formats.

Getting Started and Installation

Getting started with Docusaraus is pretty straightforward. The first thing you need to do is head over to your terminal and run the command below:

npx create-docusaurus@latest my-website classic

Note: The Docusaurus team recommends the classic template because it is easier to get started with fast. It also contains @docusaurus/preset-classic – which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support).

Project structure

After installation, this is what your newly created Docusaurus project structure should look like:

📦my-website
┣ 📂blog
┃ ┣ 📂2021-08-26-welcome
┃ ┃ ┣ 📜docusaurus-plushie-banner.jpeg
┃ ┃ ┗ 📜index.md
┃ ┣ 📜2019-05-28-first-blog-post.md
┃ ┣ 📜2019-05-29-long-blog-post.md
┃ ┣ 📜2021-08-01-mdx-blog-post.mdx
┃ ┣ 📜authors.yml
┃ ┗ 📜tags.yml
┣ 📂docs
┃ ┣ 📂tutorial-basics
┃ ┃ ┣ 📜congratulations.md
┃ ┃ ┣ 📜create-a-blog-post.md
┃ ┃ ┣ 📜create-a-document.md
┃ ┃ ┣ 📜create-a-page.md
┃ ┃ ┣ 📜deploy-your-site.md
┃ ┃ ┣ 📜markdown-features.mdx
┃ ┃ ┗ 📜_category_.json
┃ ┣ 📂tutorial-extras
┃ ┃ ┣ 📂img
┃ ┃ ┃ ┣ 📜docsVersionDropdown.png
┃ ┃ ┃ ┗ 📜localeDropdown.png
┃ ┃ ┣ 📜manage-docs-versions.md
┃ ┃ ┣ 📜translate-your-site.md
┃ ┃ ┗ 📜_category_.json
┃ ┗ 📜intro.md
┣ 📂src
┃ ┣ 📂components
┃ ┃ ┗ 📂HomepageFeatures
┃ ┃ ┃ ┣ 📜index.js
┃ ┃ ┃ ┗ 📜styles.module.css
┃ ┣ 📂css
┃ ┃ ┗ 📜custom.css
┃ ┗ 📂pages
┃ ┃ ┣ 📜index.js
┃ ┃ ┣ 📜index.module.css
┃ ┃ ┗ 📜markdown-page.md
┣ 📂static
┃ ┣ 📂img
┃ ┃ ┣ 📜docusaurus-social-card.jpg
┃ ┃ ┣ 📜docusaurus.png
┃ ┃ ┣ 📜favicon.ico
┃ ┃ ┣ 📜logo.svg
┃ ┃ ┣ 📜undraw_docusaurus_mountain.svg
┃ ┃ ┣ 📜undraw_docusaurus_react.svg
┃ ┃ ┗ 📜undraw_docusaurus_tree.svg
┃ ┗ 📜.nojekyll
┣ 📜.gitignore
┣ 📜babel.config.js
┣ 📜docusaurus.config.js
┣ 📜package.json
┣ 📜README.md
┗ 📜sidebars.js

Now, let’s explore some of the main directories:

• blog/: This is where you store your blog posts

• docs/: As the name implies, this is where your documentation projects are kept

• src/: This directory allows you to customize your website further using React code.

• static: Here, you store static files like images, logos, favicons, and so on.

A very important file is the docusaurus.config.js file, which acts as the main configuration file for your website.

How to Start Your Docusaurus Website

To run your website locally, first open a new terminal on your IDE and run the following command below to start the development server:

cd my-website

npm i

npx docusaurus start

After running the above command, the browser compiles the React and Markdown files and starts a local development server at http://localhost:3000/. Docusaurus enables hot reload, so you can see changes made to your React, Markdown, and MDX files automatically – without reloading your entire app.

Here is what the site looks like on your browser:

In the image above, you are first welcomed to an intuitive and easily navigable website. At the top left corner of the website, you will see the “Tutorial” and “Blog” sections.

• Tutorial: This is where users can see the live version of your documentation.

• Blog: This is where users can see the live version of your blog.

The link to the Docusaurus Open Source GitHub repo and the icon for toggling your website between light and dark modes are at the top-right corner of the site.

Alternatively, you can use docusaurus.new to test Docusaurus quickly in a playground without having to go through the installation process. Here, you have an option to choose between CodeSandbox and StackBlitz.

How to Create Documentation (Overview)

Let’s take a closer look at our docs folder. If we head back to our local site and click on “Tutorial,” we will see some pre-built doc pages, as shown below:

These documentation pages are reflected in the docs folder located in your IDE. When we open the category.json page, we can adjust the name or position of each page. This means you don’t have to name the folders the same as the page name, since the name of the file will be the URL of the page.

To create our new documentation, let’s use the following steps:

1. Delete all the files in the docs folder. Your browser and terminal will typically display an error after this.

   

   This is because we need at least one page in the docs folder.

2. Create a new file inside the docs folder, which can be named anything you prefer, but in our case, I named it single-page.md. You should see this change immediately reflected when you go to your local website. This is what you will see in the documentation pages section:

   

Inside this newly created file, you can create your documentation seamlessly. The image above shows the little Markdown content I created saying “Single Page” in an H1 and “This is a single page” in plain text.

Let’s say you want to create a more organized content structure, but you don’t know how to get started. Here are a few simple steps on how to do that:

1. Create a new folder inside the docs folder, named “Getting Started”

2. Create new Markdown files inside the “Getting started” folder, and name them whatever you like. For the sake of this tutorial, let’s name it API-docs.md and Session-replay.md.

3. Write your documentation in Markdown

This is how the file structure should look like on your IDE:

📦docs
┣ 📂Getting started
┃ ┣ 📜Open-replay.md
┃ ┗ 📜Session-replay.md
┗ 📜single-page.md

Here is a simple GIF to demonstrate how this works on the local documentation website.

Now, let’s try to create a separate page in the doc folder. To do this, let’s create a category.json page in the Getting started folder. Inside the category.json file, we will include the following JSON text:

{
  "label": "Custom Title",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "This is a custom description"
  }
}

• The link object creates a separate page for the folder.

• The type property is set to generated-index, which means it will generate the pages with all the sub-pages.

• The description property is a description of the page that will show up beneath the title.

When you check out your local hosted documentation site, you will see that the label has changed, and a separate page has been created for the folder.

In this section, I will show you an example of how headings and tables of content work in Docusaurus.

The first thing I did was create a markdown.md file. Then I pasted a couple of headings in Markdown text format right inside the file, like this:

---
title: Basic Markdown
sidebar_position: 1
---

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

When we head back to our website, we can see that only headings level 2 and 3 are automatically added, just as shown below:

We can edit to ensure that all the headings show up. To do this, first create a table-of-contents.md, then paste in the following Markdown:

---
title: Table of Contents
sidebar_position: 2
toc_min_heading_level: 2
toc_max_heading_level: 6
---

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} minHeadingLevel={2} maxHeadingLevel={6} />

## Heading 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.

### Heading 3

Some content here.

#### Heading 4

Some content here.

##### Heading 5

Some content here.

###### Heading 6

Some content here.

## Heading 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.

### Heading 3

Some content here.

#### Heading 4

Some content here.

##### Heading 5

Some content here.

###### Heading 6

Some content here.

## Heading 2

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed non risus. Suspendisse lectus tortor, dignissim sit amet, adipiscing nec, ultricies sed, dolor.

### Heading 3

Some content here.

#### Heading 4

Some content here.

##### Heading 5

Some content here.

###### Heading 6

Some content here.

I added a TOC property and set the minimum and maximum heading levels with toc_min_heading_level: 2 and toc_max_heading_level: 6. We also added an inline table of contents by first importing TOCInline from @theme/TOCInline. Then, we created a TOCInline component (which can be put anywhere you want your TOC to show up).

Now, all the headings show up in the table of contents part of the website:

Beautiful right?

MDX and React Components

Now, let’s talk about one of the most exciting features of Docusaurus: MDX and React components.

You might ask – how can Docusaurus use TOC or import in the Markdown file? Well, that’s because Docusaurus uses MDX, which is basically Markdown with JSX.

To demonstrate this, let’s create a new Markdown file inside our Getting started folder titled MDX.md , then we create a separate file inside the src > components folder and name the file Tag.js . Then we paste in the following code:

import React from 'react';

export default function Tag({ children, color }) {
  return (
    <span
      style={{
        backgroundColor: color,
        borderRadius: '4px',
        color: '#fff',
        padding: '0.2rem 0.5rem',
        fontWeight: 'bold',
      }}
    >
      {children}
    </span>
  );
}

Here, we first imported the core React library, and then we defined a functional component called Tag, which takes in two props as input: children and color. In our return statement, we included our CSS styles for the span element.

Inside the MDX.md file, paste in the below code:

---
title: MDX
sidebar_position: 3
---

import Tag from '@site/src/components/Tag';

<Tag color="#FF5733">Important</Tag> information: This is an <Tag color="#3399FF">Exciting</Tag> example of custom components!

I can write **Markdown** alongside my _JSX_!

Here, we import Tag from our components folder. This is what it looks like:

Note: Because we use MDX, Docusaurus comes with pre-built components like Tabs, alerts, code blocks, and more. Let’s check them out in the following subsections.

Tabs

In this subsection, we’ll talk about tabs as a pre-built component in Docusaurus. Let’s dive right in!

For a start, let’s create a new Markdown file called tabs.md and paste in the following code:

---
title: Tabs in Markdown
sidebar_position: 4
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="book" label="Book" default>
    Dive into the world of knowledge with a captivating book 📚
  </TabItem>
  <TabItem value="painting" label="Painting">
    Admire the strokes of artistry on a beautiful painting 🖼️
  </TabItem>
  <TabItem value="music" label="Music">
    Let the soothing melodies of music transport you 🎶
  </TabItem>
</Tabs>

I'm a text that doesn't belong to any tab. So I'm always visible.

We imported Tabs from @theme/Tabs and TabItem from @theme/TabItem. Then, we created a Tabs component, which is the container, and the TabItem component is the tab itself. The value property is the value of the tab, while the label property is the label of the tab. The default property defines which tab is open by default – in this case, the “Book” tab.

This is how it looks:

Each tab is clickable and transitions smoothly.

Alerts or Admonitions

Docusaurus comes with pre-built alerts or admonitions. To create an alert, you simply wrap the text with three colons and follow it with the type of alert you want the reader to have in mind.

Let’s create a new Markdown file called alerts.md and paste in the following Markdown:

---
title: Alerts or Admonitions
sidebar_position: 5
---

:::note

Here's some **information** with _Markdown_ styling.

:::

:::tip

Here's a **helpful tip** with _formatted text_.

:::

:::info

Here's some **useful info** presented in a clear way.

:::

:::caution

Please take **extra caution** with this important note.

:::

:::danger

This is a **dangerous situation** you need to be aware of.

:::

:::note This is a _custom title_

And you can add images as well.

![alt text](https://picsum.photos/600/400)

:::

The various types of alerts, as shown in the Markdown above, are:

• note

• tip

• info

• caution

• danger

Here’s what it looks like on the website:

Alerts and admonitions are pretty common in documentation sites. So, if you have ever wondered how it’s been done, well, this is it! It’s quite straightforward.

Code blocks

As we already know by now, Docusaurus supports MDX, which allows us to include code blocks in our files. Code blocks are text blocks wrapped around by strings of three backticks. You can add the name of the language after the last of the three backticks.

Let’s create a codeblocks.md file and paste the following JSX code:

---
title: Codeblocks
sidebar_position: 6
---

```jsx title="Codeblock"
function Greeting(props) {
  return <p>Welcome, {props.userName}!</p>;
}

export default Greeting;
```

```jsx title="Highlight Lines"
function HighlightText(highlight) {
  if (highlight) {
    // highlight-next-line
    return 'This text is highlighted!';
  }
  return 'Nothing highlighted';
}

function HighlightMoreText(highlight) {
  // highlight-start
  if (highlight) {
    return 'This range is highlighted!';
  }
  // highlight-end
  return 'Nothing highlighted';
}
```

```jsx title="Line Numbers" showLineNumbers
import React from 'react';

function UserProfile(props) {
  const { username, email, isAdmin } = props;

  return (
    <div>
      <h1>User Profile</h1>
      <p>Username: {username}</p>
      <p>Email: {email}</p>
      {isAdmin && <p>Admin User</p>}
    </div>
  );
}

export default UserProfile;
```

```jsx title="Line Numbers with Highlight" {4,9-11} showLineNumbers
import React from 'react';

function UserProfile(props) {
  const { username, email, isAdmin } = props;

  return (
    <div>
      <h1>User Profile</h1>
      <p>Username: {username}</p>
      <p>Email: {email}</p>
      {isAdmin && <p>Admin User</p>}
    </div>
  );
}

export default UserProfile;

This is what the code blocks look like:

You can easily copy the code by hovering your cursor over the code blocks and clicking on the copy icon on the top-right side of the code block.

Note: By default, Docusaurus uses Prism for syntax highlighting.

If you also want to highlight some lines of code, you can do that by adding a comment like this:

    // highlight-next-line
    return 'This text is highlighted!';
  }
  return 'Nothing highlighted';
}

function HighlightMoreText(highlight) {
  // highlight-start
  if (highlight) {
    return 'This range is highlighted!';
  }
  // highlight-end

• highlight-next-line: allows you to highlight a single line of code

• highlight-start and highlight-end: allows you to highlight a range of lines

Docusaurus Blog

The Docusaurus blog also comes by default with the classic template. If you don’t have a blog, you can add the following lines to your docusaurus.config.js file:

{
  label: 'Blog',
  to: '/blog',
}

Usually, this line should already be in your config file after installing Docusaurus for the first time.

The Docusaurus blog is very simple to understand. Navigate to the blog folder in the project explorer, and you’ll see all the blog posts, which are MDX files. The blog post date should be included on the file name as shown below:

When you open one of the blog posts, you see something like this:

---
slug: long-blog-post
title: Long Blog Post
authors: yangshun
tags: [hello, docusaurus]
---

This is the summary of a very long blog post,

Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.

<!-- truncate -->

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

• slug: You can add a slug to the URL of the blog post

• title: Title of the blog post

• authors: The authors of the blog post

• tags: Tags related to the blog post

In the blog post, we can also use all the Markdown features plus JSX as we have seen before.

Custom Pages

Technically, Docusaurus isn’t just a fancy documentation site generator with a blog. It’s a standard static site generator – which means you can create any page you want.

To see how creating a custom page in Docusaurus works, let’s create an about.js file in the src > pages folder and include the following code:

import React from 'react';
import Layout from '@theme/Layout';
import Head from '@docusaurus/Head';

export default function About() {
  return (
    <Layout>
      <Head>
        <title>About</title>
        <meta name="description" content="This is the about page" />
      </Head>

      <div>
        <h1 className="red-text">About</h1>
        <p>This is the about page.</p>
      </div>
    </Layout>
  );
}

When you go to http://localhost:3000/about, you should see something like this:

We can also add the page to the navbar by going to the docusaurus.config.js file and adding a new item to the navbar array. The item looks like this:

{to: 'about', label: 'About', position: 'left'},

It then appears on the homepage nav menu like this:

You can now style and customize the about.js file any way you’d prefer using React.

Styling in Docusaurus

Let’s look at how you can style your site in Docusaurus. The easiest way is to customize the custom.css file inside the css > custom.css file. This is what the file looks like:

Here, you can change the whole color schema of the site and different styling to this file.

You can read more about this in the Docusaurus styling and layout docs.

SEO in Docusaurus

Docusaurus takes SEO very seriously. By default, Docusaurus automatically adds a description title, canonical URL links, and other useful metadata to each page. This can be configured as shown below:

---
title: Our First Page
sidebar_position: 1

description: A short description of this page
image: ../static/img/docusaurus-social-card.jpg
keywords: [keywords, describing, the main topics]
---

# Single Page

This is a single page.

You can read more about this in the Docusaurus SEO docs.

Deployment

Deployment is pretty easy with Docusaurus. Since it’s a static site, you can deploy it to any static site hosting service. To do this, run the npm run build command on your CLI. This creates a build folder like the one below:

Then, you can upload the contents of the build folder to your hosting service.

Conclusion

In this article, we covered how to build documentation from scratch, how to create, customize, and style pages, and the awesome SEO power of Docusaurus.

Docusaurus is friendly to both developers and technical writers. As a developer, you can focus on customizing the site, while as a technical writer, you can focus on writing the documentation.

I will highly recommend this tool for both startups and established enterprises looking to build stunning documentation sites.

This guide is not exhaustive, but covers everything you need to know about the basics of building a documentation site with React and Docusaurus.

I hope you found it helpful :)

Here’s the link to my GitHub code for follow-up purposes.

And here’s the main Docusaurus documentation if you’d like to dive in deeper.

Usually, a QA tester creates a report after discovering a bug. The next step is that they send a report to the bug handler. Basically, a bug handler is a developer that fixes a bug according to the detailed report. The bug handler ensures a clean and efficient QA process and makes it easier to have a clean conversation between the fixers and the testers.

But you might be wondering – why do we need QA documentation?

QA testing is essential in IT products today. Tight deadlines, unique skill sets within the organization, and the demand to develop products stress the need for a structured methodology. QA documentation guides testers through levels of clarity and overall coverage.

I've written this article to make your life a bit easier. So here it is, your ultimate guide on how to write software QA documentation that will work.

This is what we'll cover:

• Make a Test Plan and a Test Progress Report
• Create Test Cases
• Defect Reports
• Useful Tips for Defect Report Writing
• Submit a Defect Report
• Conclusion

Make a Test Plan and a Test Progress Report

Developing great software requires a thorough and documented approach to testing. Everything begins in the development phase with a complete checkout plan as a template for the entire QA process. It outlines the general requirements, defines the followed route, identifies the necessary assets, and sets a simple timeline for achieving the objectives.

Draw up a roadmap before you start

Before you start implementing your test plan, take some time to think about the big picture. Ask yourself:

What problem does this software solve? As soon as you understand the main purpose of the software, you'll be able to manage the checkout process and identify the features that are most important to your goals.

I promise that once you see that you can do this, you quickly prioritize your efforts. They are based primarily on the importance of the functionality and its impact on the user.

Create a plan

The test plan is the central part of the QA technique. The test plan should contain the following key elements:

• Imaginary test: Clearly identify the expected impact of the payment method. Will it confirm that core functionality is running smoothly, or will it alert you to capability gaps?
• Test method: Outline how the test will be performed. Will you do targeted testing, useless testing, or a mix of the two?
• Resource allocation: Identify the equipment and technology required to perform a complete control. What control framework will you use? Are specific hardware or software configurations required for proper control?
• Timetable and remaining dates: Establish a realistic timetable for the trial. Set clear deadlines to keep the project on track.

Understand the 'why' and 'how'

A well-developed roadmap will ensure that key issues are addressed throughout the improvement approach:

• Acceptance requirements: Clear fail/success criteria should be defined for all control cases. So, criteria allow the customer to understand that the product is high quality and ready for the end-user.
• Resource management: Identify the assets required for the testing. This includes preferred machines, copies of software in various forms, required expertise, and more.
• Team dynamics: Ensure that simple roles and tasks are defined within the test team. Who is responsible for particular test cases? Who documents bugs and who talks to developers?
• Time management: I advise setting realistic checkout times, taking into account project deadlines and the availability of useful help.

The test progress report is another part of the QA documentation, similar to the test plan, but with additional data on current progress. This document allows you and your development team to monitor project progress and identify any organizational issues.

A test plan and a progress report

Create Test Cases

Think of each test case as a detailed recipe for finding potential defects in the functionality of a software program. By following these "recipes" and evaluating the expected and actual results, defects can be accurately identified and addressed before preventive action is taken.

Each test case acts as an independent unit, outlining the steps required to evaluate a particular element of a software program.

Below is a breakdown of the key elements that make up a well-defined test case Here is my step-by-step guide for creating test cases:

• ID: This is an identifier field to help distinguish between test cases and track them easily.
• Priority: This indicates the severity of the test case based on the functionality of the program and its impact on the normal overall performance of the known software program application.
• Test Requirements: These are requirements for testing software successfully, this can include reference documents also.
• Software Module: This shows the feature under testing. It also refers to the software requirements specifications (SRS) document explaining the software feature in detail.
• Test Context: This details the test plan to clarify how the daily tests will be carried out. It also identifies the test data required for a successful case study and includes unique and important statistical information.
• Expected Output: This describes the expected output to be displayed if the test is successful.
• Actual output: This indicates the actual result in the event of failure and shows the developer the errors in the application module of the software program.
• Comment: This is an optional section where the tester can give a description of the observations or add additional records.

All QAs typically include the above elements, but can also be designed specifically for the task selected by the QA group. Also, each control case follows a lifecycle that defines the phases of creation, testing (pass, fail), completion, and so on.

In the next section, we’ll check out another important element of QA documentation: the defect report.

Test cases

Defect Reports

Defect reporting is an important element of QA documentation. Issue tracking is the detailed reporting of sudden problems that arise in a software product. Careful documentation of these issues lays the groundwork for a complex and bug-free final product.

Sounds simple, right? Yes, but only until you start documenting.

A defect report

The bug report consists of the following sections: Identifier, Summary, Description, Steps to Reproduce, Reproducibility, Severity, Priority, Environment, and Attachments.

• Identifier: Each software program problem is assigned a completely unique identifier that acts like a customized nameplate. This makes the QA documentation less complicated to navigate and allows verbal communication between the installer, tester, and project manager (PM).
• Summary: This is an opportunity to provide brief and informative answers to three basic questions: What was the problem? Where did the problem appear? Under what specific conditions did the problem appear?
• Explanation: Examine the failure log in more detail. Summarize the identified action (the result completed) and check it against the planned action (the predicted end result). Including a link to the app requirements of the software program can serve as a useful reference element.
• Reproduction method (STR): This phase should be considered as a step-by-step recipe for reproducing the defect. It should be strict and cover all the steps that caused the problem. Skipping critical steps can make it difficult for you to reproduce the problem and cause delays.
• Reproducibility: In this section, you clarify if the bug appears every time you follow the STR. You should use numbers to show approximate chances, for example, 7 times out of 10.
• Severity: Here you explain how much harm the bug may bring to the project. Essentially, this is a measure of the severity of the technical disruption that a bug will cause to the whole project. Remember that problems that are known to be minor can grow and cause you extreme problems throughout the software.
• Priority: Each error log assigns a problem priority that indicates its urgency. Common priorities are letters (A: highest priority, Z: highest priority), numbers (1: highest priority, 9: highest priority), or descriptive terms (high, medium, low).
• Environment: Specify the gadget or browser model in which the bug appeared. This will help you to put the problem in context and narrow down a valid cause.
• Attachments: If possible, enrich the documentation with screenshots, screen recordings, console log documents, and others. This will help to provide visual documentation of the error.

My structure provides detailed information, so you can empower developers to effectively diagnose, address, and eliminate any software bugs. In this way, leading to more user-friendly and robust products.

Now, in the next section, we'll see some useful tips you can use for defect report writing.

Useful Tips for Defect Report Writing

1. Write a sufficient summary. It does not matter if it is long or short. What matters is that it should be clear.
2. Have a look at the summary and the description. Do they look pretty much the same? You must have forgotten to outline the expected and actual results in the description and to add the link to the requirements.
3. Capture the issue with the help of a screenshot. It may save you and the development team a lot of time. Sometimes one glance at the picture is just enough to understand the situation.
4. Before reporting the issue, try to reproduce it at least 3 times to be sure that it exists.
5. Report the issue ASAP and notify your project manager or product owner if the issue is major.
6. Check for grammar mistakes in your QA documentation so you're not taken down by the grammar police.
7. However comical it sounds, make sure that the issue is not a feature – review the documentation again!
8. Do not miss any important information in your Steps to Reproduce.

Submit a Defect Report

The final and one of the most important elements of QA documentation is the defect report. You may understand it covers the entire lifecycle of a problem, from its initial discovery to its final closure.

Let's now examine the key areas of this process:

a defect report lifecycle

We'll go over the defect report lifestyle piece by piece:

Problem Reporting:

This adventure begins with the careful compilation and submission of a report on the entire program. This serves as a roadmap for developers and provides a clear assessment of the problem.

Triage and tasks:

The task manager or technical lead takes on the role of gatekeeper at this stage. They carefully compare the files. If the file contains enough elements to work with, it is assigned to the developer and repaired. However, if the file is missing essential elements, it may be rejected for further improvement.

Bug fixing:

The assigned developer takes the initiative and works diligently to eliminate the annoying bug.

Verification and completion:

Once the developer claims to have fixed the problem, it's your turn as QA. Carefully verify the fix by retesting the functionality in question. If everything works as it should, you are done.

The documentation has come to a happy end. Ideally, this will happen within a reasonable period of one to two weeks.

Reboot and keep going:

But it is not always that simple. If it is known that bugs are still being made in the validation system, there is no need to despair!

Re-open the bug documentation and send it to the developers for further attention. Sometimes the process of fixing bugs is repetitive and requires patience. But by being careful and effective, you can guarantee that all bug reports will eventually reach their final destination, resulting in a more polished and reliable software application product.

Conclusion

Quality Assurance is a process you simply cannot avoid. Each airplane prior to departure undergoes a technical check. If there is any issue, the aircraft is grounded until the problem is solved. The same goes for any software.

But QA documentation is not always "write and ignore". At some point in the software development lifecycle, QA documentation needs to be continually updated and improved as requirements change, new features are introduced, and feedback is received from deployment and production use.

There are also a growing number of styles that use synthetic intelligence and machine learning to partially automate the creation of QA documentation.

For example, natural language processing (NLP) is used to analyze requirements documents and generate draft control examples. Test bots can use NLP to interpret and routinely execute directed test cases. Predictive evaluation can also be used to identify the most dangerous areas of a software program that require more detailed control.

While these strategies are still new and not mature enough to replace human testers, they can help with growth and augment manual exploration, especially for large and complex builds. By making QA documentation a collaborative and ongoing hobby, your team can deliver better software faster and with fewer defects.

Do you need to improve the quality of your software?

My company KeenEthics provides solid development and quality assurance services. In case you need an estimate for a similar project, feel free to get in touch.

If you have enjoyed the article, you should continue with How IT Outsourcing Saves Costs for Your Company and Avoiding Pitfalls in IT Outsourcing: Tips for Minimizing Risks.

GitHub wikis are easy to start using without installing any other software. The best part is that the wiki is integrated with your GitHub repository.

You do not need any other tool – you just need to know how to use markdown, as you'll use it to write your wiki. (You can read all about that in my other article here.)

How to Start Using GitHub Wiki

You can start your GitHub wiki with just one click. Every GitHub repository has a Wiki tab in the menu at the top of the page. To start, click on it.

GitHub repository Page

The wiki tab is sometimes not shown by default in the GitHub repository nav bar. First, you'll need to enable wikis in your repository settings.

No wiki tab is shown.

To do that, go to your repository settings page, scroll down, and find the features section. Then enable wikis by checking the "Wikis" box.

Enable wiki

To initialize the wiki in your GitHub repository, create the home page in your wiki.

Initialize the wiki in GitHub.

When you click the "Create the first page" button, you'll be redirected to the editor page where you can create a home page in the wiki.

Create a home page and initialize the wiki.

Your wiki home page should now look like this:

Wiki home page

How to Clone a GitHub Wiki Locally

Sometimes, new developers are confused about how to clone the wiki locally. To do this, just copy the link where it says “Clone this wiki locally”, as you can see in the image below:

Copy the link to clone the GitHub wiki.

Copy that link and clone the GitHub wiki repository locally on your laptop or machine.

Now, you can make changes in the wiki, such as editing, updating, or changing documentation locally. After you finish any documentation changes, you can push your local wiki documentation to the GitHub wiki repository.

$ git clone https://github.com/officialrajdeepsingh/github-wiki-tutorial.wiki.git
Cloning into 'github-wiki-tutorial.wiki'...
remote: Enumerating objects: 6, done.
remote: Counting objects: 100% (6/6), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 6 (delta 1), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (6/6), done.
Resolving deltas: 100% (1/1), done.

How to Customize Your Wiki

Wikis have limited customization options for the sidebar, home page, and footer. But you can extend these options using HTML, CSS, and Markdown.

We have already discussed the home page, and now we'll discuss the footer and sidebar.

The footer and sidebar show or contain helpful links such as contact information, navigation links, social media links, and so on.

The footer is shown at the bottom of every page on your site, and the sidebar is typically a vertical column on the left or right side of a web page. Both are visible on all pages of the wiki.

How to create a custom sidebar

There are two ways to create a sidebar in the GitHub wiki.

1. With the GitHub UI
2. Locally in your IDE

We'll look at each method here so you can choose the one that works best for you.

With the GitHub UI

Create a sidebar

Go to the wiki home page and click on the “Add a custom sidebar” button to create a sidebar in your wiki.

Next, it will redirect you to the editor page to create a sidebar page. In the sidebar file, you can write markdown content such as navigation links, and so on. After that, click the save button.

_Create _Sidebar.md file._

Locally in your IDE

The second way is to clone your wiki locally and then create a _Sidebar.md
file in your wiki at the root level using VS Code or any other IDE which you like.

How to create a custom footer

You'll follow basically the same steps as in the sidebar section to create your custom wiki footer.

With the GitHub UI

Go to your wiki page and click on the “Add a custom footer” button to create a footer in your wiki.

Next, it will redirect you to the editor page to create a footer. In the footer file, you can write markdown content such as navigation links, and so on. After that, click the save button.

Create a footer

Locally in your IDE

The second way is to clone your wiki locally and then create a _Footer.md
file in your wiki at the root level using VS Code or any other IDE which you like.

What is a Page? How Do You Create a New Page in the Wiki?

In a wiki, a page has functionality similar to other CMSs, giving you the power to manage your content and documentation.

With the wiki page, you can divide your content or docs into different sections such as installation, configuration, and so on.

To create a new page, click on the new page button.

Create a new wiki page

It redirects you to the editor page, where you can add a title and content. After your writing is finished, click on the save button.

Create a wiki page

Your page looks like this in the wiki after it is published:

The Wiki page looks like this in the browser after publishing.

Everybody can access your pages section. Every page you publish is shown in the pages section on your wiki.

The page section shows the published page list.

How to Enable and Disable Collaboration in the Wiki

To enable collaboration for everyone in the wiki, go to your GitHub repository settings page, scroll down, find the features, and unselect the "Restrict editing to collaborators only" checkbox.

Enable Collaboration in the GitHub Wiki.

You can turn off collaboration for everyone, so that you and your team are the only ones responsible for updating, deleting, and editing the wiki.

To do this, you need to restrict editing for other users. Enabling the Restrict editing to collaborators only option quickly accomplishes this.

After there haven't been any edits, invite your team and give them access to it. Then just click the "Restrict editing to collaborators only" checkbox.

Disable Collaboration in the GitHub Wiki.

Why is GitHub Wiki So Useful?

GitHub wikis can be useful for everyone. You can start your documentation with a wiki in less than one minute. You do not need anything to start writing your documentation except basic knowledge of Markdown syntax.

Using GitHub wikis, you can just focus on writing basic documentation and on the project itself. GitHub wiki handles the rest of your documentation such as hosting concerns, search, and so on. Most importantly, for public repository wikis, it's totally free.

Many famous open-source projects use Wiki nowadays, such as hhvm, neovim, guard, foundation db, and others.

Check out the list of projects used in Wiki.

Conclusion

There are many documentation frameworks on the market, such as Nextra, Lume, Starlight, and Docusaurus. But they take some time to learn, configure, and set up.

Also, if you're still working on your coding skills and you aren't comfortable with tools like React, MDX, and so on, you'll need to take some time to learn them before using these more advanced documentation frameworks.

With GitHub Wiki, you can start creating your documentation right away, and you do not need to worry about deploying and hosting anything managed by GitHub.

GitHub Wiki is a great choice for small and early-stage projects. You and your team can focus on the project while composing straightforward documentation.

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.‌