Quick start guide

This guide will help you get started with the documentation project. It covers the following:

How to contribute to the documentation project by creating your own topic.

Prerequisites

A basic understanding of Git, GitHub workflow, and common Git commands is highly recommended. If you are new to Git, refer to the Git Workflow documentation for more details.

Install and configure Git.
Create a GitHub account and request access to the Documentation team in the Metamation GitHub organization. As a member of the Documentation team, you will have access to all documentation repositories.

Contact Sanjiv Doraiswamy for access.
Install the required tools.

Create your own topic

Use the Git command line instead of a desktop application. The command line gives you full control over Git operations, makes it easier to troubleshoot issues, and ensures consistency across different environments.

Before you start writing, identify your product document and its corresponding GitHub repository. Refer to the Documentation Index for the list of products and their documentation repositories.

Follow the steps below using the command line to create your own topic:

If you are a first-time contributor, use git clone <repository_url> to clone the repository to your local machine. . If you are a returning contributor, make sure you are on the main branch and pull the latest changes using git pull.
Create a new branch for your topic using git switch -c <branch_name>.

Branch naming convention

If you have access to FogBugz → Documentation project, create a case for your topic and use the format for branch name: Case.<case_number> where <case_number> is the FogBugz case number. For example, if you are working on a topic related to case number 12345, your branch name could be Case.12345.

If you don’t have access to FogBugz, use the format for branch name: <short_description> where <short_description> is a brief description of the topic you are working on. For example, if you are working on a topic related to installation, your branch name could be installation. Notify the documentation team about the branch you created so they can create a corresponding case in FogBugz for tracking purposes.

Use code . to open the current branch in Visual Studio Code.

Identify the topic placement

Before creating a new topic, determine where it belongs within the documentation structure. Familiarize yourself with the product document and its layout, then use the Explorer pane in Visual Studio Code to find the appropriate location for your topic.

Your topic will fall into one of these categories:

A new file to be added to the documentation structure with text and images.
An existing file to be updated with new or revised text and images.

Ensure that your topic includes relevant images where needed. Use the Snipping Tool to capture screenshots and save them as .png files in the corresponding img folder within the documentation structure.

Style guidelines

It is important to follow the Style Guide when writing documentation. Consistent formatting across all topics reduces the review effort and speeds up the publishing process.

Document your topic with AsciiDoc syntax

Whether creating a new file or updating an existing one, write your content and mark it up using AsciiDoc syntax. A basic understanding of AsciiDoc is needed for this step.

Refer to the AsciiDoc Syntax Quick Reference for more details.

Once your topic is marked up, you can preview it in Visual Studio Code to see how it will look in the final documentation.

Save the file and run bento to build the HTML output. See Bento structure for details on how Bento works.

On a successful build, your topic will be visible in the generated HTML file. If any errors occur, correct them and rebuild until you are satisfied with the result.

Commit and push your changes

Follow the steps below to commit and push your changes to the remote repository:

Use git add <file_name> to stage the file you created or updated. You can also use git add . to stage all your changes at once.
Use git commit -m "<commit_message>" to commit your changes with a descriptive commit message. For example, if you created a new topic on installation, your commit message could be "Add installation topic for Product X".
Use git push --set-upstream origin <branch_name> to push your branch to the remote repository. This also sets up tracking so that future pushes only require git push.
After pushing your changes, create a pull request in GitHub and add a documentation team member in the assignees field.

The documentation team will then review your pull request, apply any final formatting adjustments if necessary, and merge it into the main branch. Once merged, your topic will be published by the documentation team.

Congratulations! You have successfully created your own topic and contributed to the documentation project.