Skip to main content

Authoring Documentation

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

Tech Stack​

The DQX 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 DQX 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 DQX 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.

For cases when images have transparent backgrounds, use the following syntax:

<div className='bg-gray-100 p-4 rounded-lg'>
  <img src={useBaseUrl('/img/dqx.png')} alt="DQX" />
</div>

This will add a gray background to the image and round the corners.

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.

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.