Skip to main content

Authoring Documentation

This document provides guidelines for writing documentation for the UCX project.

Tech Stack​

The UCX documentation is built using Docusaurus, a modern static site generator. Docusaurus is a project of Facebook Open Source and is used by many open-source projects to build their documentation websites. We also use MDX to write markdown files that include JSX components. This allows us to write markdown files with embedded React components. For styling, we use Tailwind CSS, a utility-first CSS framework for rapidly building custom designs.

Writing Documentation​

Most of the documentation is written in markdown files with the .mdx extension. The markdown files are located in the docs directory of the UCX project.

Prerequisites​

Before you start writing documentation, make sure you have the following tools installed on your machine:

On macOS, you can install Node.js and Yarn using Homebrew:

brew install node
npm install --global yarn

Setup​

To set up the documentation locally, follow these steps:

  1. Clone the UCX repository
  2. Run:
make docs-install

Running the Documentation Locally​

To run the documentation locally, use the following command:

make docs-serve-dev

Checking search functionality​

Tip

We're using local search, and it won't be available in the development server.

To check the search functionality, run the following command:

make docs-serve

Adding images​

To add images to your documentation, place the image files in the static/img directory.

To include an image in your markdown file, use the following syntax:

![Alt text](/img/image-name.png)
Tip

Images support zooming features out of the box.

Linking pages​

It is strongly recommended to make all links absolute. By doing so we ensure that it's easy to move files without losing links inside them.

To add an absolute link, use this syntax:

[link text](/docs/folder/file_name)

Always start with /docs. The file extension .md or .mdx can be omitted.

To add an anchor to a specific heading, use this syntax:

[link with anchor](/docs/folder/file_name#anchor)

After writing docs, run this command:

make docs-build

It will throw an error on any unresolved link or anchor.

Content alignment and structure of folders​

When writing documentation, make sure to align the content with the existing documentation.

The rule of thumb is:

Do not put any technical details in the main documentation.

All technical details should be kept in /docs/dev/ section.

No need for:

  • Source code links
  • Deep technical details
  • Implementation details

Or any other details that are not necessary for the end-user.

Deployment​

The UCX documentation is hosted on GitHub Pages, and the deployment process is automated using GitHub Actions.

To configure the deployment process, you need to have admin permissions on the repo:

  1. go to the repository settings -> Pages
  2. In the "Build and deployment" section select the Github Actions source.

The deployment process is triggered automatically when a release is created. Also, the deployment process can be triggered manually from the Actions tab in the GitHub repository by privileged users.