Contribute to Matillion's docs

Matillion's documentation is extensive in our mission to provide comprehensive help and reference for all of our users across our products and services. Our documentation can be described as "living documentation", meaning our work is never finished, as the products evolve and we continuously update and maintain the documentation to high standards.

We encourage feedback internally and from our customers, and equally encourage input to our documentation. By making our docs repo open source, you're free to contribute to Matillion's high-quality technical documentation, and to help us to continue to improve our service.

Tip

Before contributing to our docs, read our Contribute to docs prerequisites to ensure you have all tools and dependencies installed on your computer.

Note

When contributing to our docs, use our style guide (this guide is a continuous work-in-progress) for all matters related to writing decisions and style.

Our documentation is stored and managed as a library of Markdown files .md in a GitHub repository. This method is known as 'docs-as-code' because we are writing documentation in the same technical manner as developers manage code. Contributors will connect to our repository and create branches to work locally, with subsequent pushes being reviewed by the docs team and relevant subject matter experts (SMEs) before a merge takes place. Once a development branch has been merged to main, our CI/CD pipelines deploy the merged changes to docs.matillion.com.

Overview of the repo

Matillion's documentation is version-controlled, and its repository is hosted on GitHub.

Note

Nobody can push commits to the main branch, meaning you must create a development branch for any changes you wish to proffer to main.

Any pull request that requests to merge a development branch into the main branch requires at least one member of our documentation team to approve the pull request. Additionally, subject matter experts (SME) may also offer their feedback as part of the code review. Once all approval criteria are met, a branch can be merged.

Clone the repo

Clone the matillion-docs repository to your local machine to begin contributing.

Warning

Before you can clone the repo, you'll need an SSH key. Read Generating a new SSH key and adding it to the ssh-agent to learn more.

Visit our GitHub repo.
Click <> Code.
Ensure the Local tab is active.
Ensure the SSH subtab is active.
Click the copy button or highlight the URL: git@github.com:matillion/matillion-docs.git
Open your CLI.
Navigate to a folder you wish to clone this repository into. Typically you might run cd documents to clone the repo into your Documents folder.
Run git clone git@github.com:matillion/matillion-docs.git in your CLI. The cloning process will take a few minutes.

Create a development branch

Make changes in a development branch. Changes can't be made to the main branch for security and integrity purposes.

Changes might include:

Updates to existing docs.
Deleting redundant docs.
Creating new docs.

Branch names

At Matillion, the docs team relates its Git branches to Jira tickets. So if there's a Jira ticket with the key DOC-123, the writer should name the corresponding Git branch DOC-123. However, if you're contributing to the docs from outside the docs team, use the following conventions for naming branches:

feature/: For new content or feature documentation.
bugfix/: For fixing typos, broken links, or other minor errors.
hotfix/: For urgent fixes in production documentation.
update/: For updates to existing content.

Additionally, we advise that you:

Use your initials or first name after the prefix.
Keep the branch name short but descriptive.

For example, if your name is Mia and you want to add a section to our Schedule feature docs, you might name your branch feature/mia-new-schedule-section.

Create a new branch

Open your CLI.
Navigate to your local copy of the repo. For example cd documents/matillion-docs would change directory to Documents > matillion-docs in your filesystem.
Run git status to confirm your current branch and its status.
1. If you are on main, run git pull to pull in latest changes. You can now run git checkout -b new-branch to create a new branch, in this case called new-branch.
  1. Only use -b when checking out to a new branch. Future checkouts to that branch don't require the -b flag.
2. If you're not on main when you run git status, clean up any previous work and run git checkout main and complete the step above this one.

Note

Get into the habit of performing git pull whenever you return to main and if you return to a development branch after some time—especially if someone else might have worked on your branch.

Create, edit, or remove files

When modifying Matillion's docs, refer to our style guide (this guide is a continuous work-in-progress).

Creating files

To add a new page, follow these steps while working in your development branch:

Open Visual Studio Code.
Press CMD + p on Mac or CTRL + p on Windows to open the command palette and then type mkdocs.yml and press ENTER.
In mkdocs.yml locate the section called Nav, which starts from line 4. This nav is a structured list of all the pages across our website. The nav is listed chronologically based on how you'd see pages on the site.
Locate the product and category that you need to add a new page to. For example, Matillion ETL on line 6 is a product, and Matillion ETL basics is a category. Line 11 is Accessing your instance—this should be considered a sub-category. The next line (line 12) is a page, and it's broken into 2 parts: the page title, and the relative link to the page.
1. Accessing the Matillion ETL Client (Amazon EC2): is the page title. The : denotes that it will point to a file.
2. metl/docs/2957722.md is the file. Make sure to include a space between the colon and the file.

Notice that the nav is deliberately indented based on the site's hierarchy of pages. Essentially there will always be a top-level product, then a category. After this, there will be pages and sub-categories (and possibly sub-sub-categories, and so on). Each object (product, category, sub-category, and page) needs a hyphen at the start of the indentation, and a colon at the end of the line (or in the case of a page, after the title and before the file path).

Note

Remember that you can build the site locally, and confirm that you have added the page at the correct hierarchical level.

In summary, to add a new page to the site, you literally just add a single line such as - Generate Job Documentation: metl/docs/2832379.md to the mkdocs.yml file. And that's a new page added to the catalog. Just make sure you save mkdocs.yml when you're finished.

Editing files

Locate the file you wish to edit. This is often most easily done by locating the URL slug and then using the Visual Studio Code command palette to open the file. For example, in the URL https://docs.matillion.com/data-productivity-cloud/designer/docs/copilot-overview/ the slug is copilot-overview and in our docs repo, our slugs represent our file names.

Open Visual Studio Code.
Press CMD + p on Mac or CTRL + p on Windows.
Type the URL slug. Select the offered item to open that docs file.
Modify and then save the file.

Removing files

If a documentation page is no longer fit for purpose, either because it is out-of-date or you have written something that effectively replaces it, then you can delete it. After your branch is merged to main, the page won't be available at docs.matillion.com.

You must be thorough in determining all related dependencies are accounted for—so there are no broken links and the navigation is still clear.

To remove a file, do the following:

Open Visual Studio Code.
Press CMD + p on Mac or CTRL + p on Windows to open the command palette and then type mkdocs.yml and press ENTER.
Remove the item you wish to delete on the specific line of the yml file.
Make sure you also remove the file from the matillion-docs repository, by right-clicking on the file name, and selecting Delete.
Find and replace any links as appropriate.

Review local changes using MkDocs

One of the advantages of a tool like MkDocs is that you can build your site locally and view it as a work-in-progress in your browser.

Open a second CLI. If you don't, you'll lock your cursor in your current CLI until you quit MkDocs.
Navigate to the docs repo again. E.g. cd documents/matillion-docs.
Run git status to ensure your new CLI window is aiming at your development branch.
Run mkdocs serve. MkDocs will begin building the most recent version of the site on that branch.
This takes 1-2 minutes typically.
If MkDocs builds successfully, it'll offer you this address: http://127.0.0.1:8000/.
Paste this address into your browser and you'll see a local build of the docs.matillion.com homepage. Use the search to find the pages you've been making changes to.

Tip

If mkdocs serve doesn't work, try python -m mkdocs serve.

http://127.0.0.1:8000/ is not a live, publicly accessible version of the site. It's your local build. Each time you're working in a branch, e.g. DOC-9999, you can have a local build of the branch open (e.g. on one of your monitors) while you write the docs in an editor of your choice, like Visual Studio Code, on another monitor.

This also means when your pull request is reviewed later on, the reviewer can checkout your branch and see your changes on their own local build.

Technical accuracy and formatting checks

Once you've finished making your changes on a development branch, make sure your content is technically accurate.

It's important to check your changes in your local build for styling and formatting issues. At this stage, you can fix any formatting discrepancies. For more information, refer to our style guide (this guide is a continuous work-in-progress).

Commit and push your changes

When you've finalized all of your checks and changes in your development branch, use the following Git commands in your CLI to commit your changes, and push them to the matillion-docs repository. In this example, you'll apply a status message to the git commit command so that others can see what you have done.

Run the following:

git status to confirm your modified files are currently untracked changes (red in the CLI).
git add . to stage your changes, adding them to the Git index (green in the CLI).
git commit -m "DOC-XXX: This is my commit message" to commit your staged changes.
1. Edit according to your branch name and commit message.
git push -u origin DOC-XXX to push your local branch to GitHub (the remote) under a new remote branch (the origin) with the name of your branch.
1. Edit according to your branch name.
2. Subsequent pushes only require git push as you've set up the local-remote connection.

Create a pull request

Visit the matillion-docs GitHub repo.
Click New pull request.
In the Example comparisons box, choose your branch.
Click Create pull request.
Modify the title if you need to, and enter a description for your pull request.
1. To create a draft pull request, use the drop-down on the Create Pull Request button and select Create Draft Pull Request, then click Draft Pull Request. Draft pull requests indicate that your work is not yet ready for review.
Click Create pull request. Members of Matillion's documentation team will automatically be assigned as the default reviewers of your pull request. The team will receive a notification on our Slack channel docs-GitHub when a pull request is created.
Add any SMEs to the Reviewers section in the right-hand items.

Note

Creating a pull request helps to make sure all code changes contributing to the matillion-docs repository are reviewed thoroughly, and are in line with the Matillion documentation's Pull Request Standards.

Pull request feedback

If your pull request receives comments and change requests, you'll need to action these by further modifying the files you've worked on and following the the steps in Create, edit, or remove files until you receive approval.

After your pull request has been approved, it can be merged. Once your pull request has been merged, a CI/CD pipeline will run and your changes will be published at https://docs.matillion.com/.

Video guide

Our Senior Developer Relations Manager, Johnathan Law, has created a video that walks through how to get set up. You can watch it here.