Making your first technical writing contribution in [#technical-documentation]

The engineering-astro repository contains source code for the LinkORB Engineering website. The website contains:

• Technical documentation written for engineering, test, system administrators, and technical writers at LinkORB
• Culture and handbook guides targeting all LinkORB team members
• Job postings and other candidate and new-hire resources
• Blog posts for customers, candidates, and open-source developers

The purpose of this guide will be to assist new technical writers with successfully completing their first contribution to the LinkORB Engineering website. Specifically, this guide will cover:

Reviewing assigned tasks

At LinkORB, Team HQ is our primary project and task tracking tool. Any tasks assigned to you will be visible at your Team HQ Dashboard. Within your assigned tasks will be helpful information like background context, acceptance criteria, and the names of subject matter experts (SMEs). Be sure to read the task details carefully before beginning.

For more information about using Team HQ, please refer to these guides.

Getting assistance

Cyans, which integrates with Team HQ, is LinkORB’s primary asynchronous communications tool. Cyans is the best place to ask clarifying questions before and during task execution.

As mentioned above, Cyans and Team HQ are integrated. This means a Cyan’s topic can be linked with a Team HQ task and any discussion in Cyans will be copied into the task history.

The easiest way to link a Cyans topic and a Team HQ task is to select + Topic from the task Links section on the right hand side of the Team HQ task. Alternatively, if you’ve already started a Cyan’s topic and want to link it to a Team HQ task, check out the Cyan’s /link slash command.

Your accounts for both Team HQ and Cyans would have been set up during the onboarding process.

Repository access

LinkORB has a “documentation as code” philosophy. This means that publishing and maintaining documentation adopts the same workflow as software development. Please review this technical documentation at LinkORB guide for further details.

To get started, a team lead or senior team member will grant you read access to the engineering-astro repository on GitHub.

New team members can be confused at not being granted write access. At LinkORB, instead of having multiple branches within the source repository, contributors submit pull requests between their forked repository and the source repository.

While branching within the source repository is not a common practice, branching is recommended within each writer’s forked repository as contributors can have multiple, concurrent tasks.

Fork the source repository

To run the application using a Codespace or locally, you must first fork the astro-engineering repository (the source repository).

Grant your team access to the fork

Grant your team lead and other team members who will review your pull requests access to your fork. Ask your team leader for a list of GitHub users. Granting access to team members lets them run your branch in a Codespace so they can verify your changes.

Running the application in a GitHub codespace

In addition to running the project locally, you can also run it using a GitHub Codespace, a development environment that runs entirely in the cloud. A benefit of using a Codespace instead of local development is that all dependency installation and server initiation is handled by the Codespace. Please refer to our Getting started with GitHub Codespaces guide for more information.

Open a Codespace against the fork (ex. [your username]/engineering-astro) and not the source repository (ex. linkorb/engineering-astro).

Running the application locally

The following steps explain how to run the application locally on your computer.

Clone your fork

Run the command below, replacing [your fork URL] with the HTTPS URL of your fork.

git clone [your fork URL]

Install the project dependencies

Navigate into the directory you cloned from GitHub and run the command below.

npm install

Start a local server

In the same directory you cloned from GitHub, run the following command.

npm run dev

npm run dev starts a local Node.js server and returns a localhost URL for you to view the website in a browser; including any changes you make to the code base.

Navigating the repository

If working in a Codespace, a cloud version of VSCode is supplied.

If working locally, you can use any IDE, however VSCode is most commonly used at LinkORB. If installed, typing code . from the project’s root directory will open the cloned repo in VSCode.

As previously mentioned, you can start a local Node.js server to review any changes you’ve made locally by running the command; npm run dev .

While not comprehensive, below is an outline of the repository directories most commonly modified by technical writers. When modifying or creating new Markdown documents within the repository, it will be done within src/pages/[directory].

/
├── public/
│   └── img/                   # Images for md files
├── src/                       # Astro site source (code + content)
│   └── pages/
│       └── about/
│       └── admin/
│       └── blog/
│   │       └── index.astro    # blog index
│   │       └── *.md|mdx       # blog posts
│       └── topics/
│   │       └── docker         # subdirectory containing Markdown files for related content
│   │       └── git            # subdirectory
│   │       └── markdown       # subdirectory
│   │       └── symfony        # subdirectory
│       └── index.astro        # home page

Review standards before making changes

Please thoroughly review LinkORB’s technical documentation guides for an explanation of LinkORB’s requirements and standards for all technical documents.

Additionally, we have git commit standards that team members use to ensure collaborators have context on each change.

Using Astro frontmatter properties

The LinkORB Engineering website is built using Astro. As such, Markdown files contain frontmatter properties (or defined parameters) at the top of the file within a three-hyphen code fence.

Frontmatter properties are principally used to pass metadata about the file to Astro components. While it’s not necessarily important that all technical writers understand the inner workings of Astro, it’s good to know that these properties are required for the site to do things like:

• Know what layout to use to format a given document
• Create lists of documents within a directory
• Enable site search features
• Load banner images

// Metadata for topics
---
layout: "$/layouts/TopicLayout.astro"
title: "Configure LinkORB's commit message template"
---

// Metadata for blog posts
---
layout: "$/layouts/PostLayout.astro"
title: "Title goes here"
subtitle: "Add subtitle here"
backgroundImageUrl: /img/code.webp
date: "2023-12-19"
author: "your-alias"
---

Using images

Including images in technical documentation can be useful in providing visual aids to readers. We have documented a guide on when and how to embed images. However it’s important for new contributors to note that:

• .webp is LinkORB’s preferred format for images, and as explained in the embedding images guide, the repository contains a helpful script to convert other formats to .webp.
• Images referenced in body content of .md files should be stored in the public/img/[directory] or sub-directories.
• Images referenced in body content of .mdx or .astro files should be stored in the src/images/[directory] or sub-directories.

Proofreading with Vale

We’ve also set up Vale to help with proofreading our documentation. Vale is a command-line tool that checks for spelling and grammar errors, as well as style and tone issues. It’s a great way to ensure that our documentation is clear, concise, and consistent.

Follow the instructions in our guide to proofread documentation with Vale.

Markdown linting

Linting markdown files is the process of checking for errors and ensuring that they adhere to a set of standards or principles. This is necessary to ensure consistency and readability in documentation.

To conduct markdown linting in this repository, we use a linter called markdownlint. To learn more about markdown linting in this repo, check out this guide.

Sync your fork

Sync your fork with the source repository before pushing your changes. As a best practice, periodically sync your fork with the source repository. See the GitHub documentation on syncing a fork.

Opening your first pull request

When making your first pull request (PR), make sure the updates you’ve made are on a new branch and follow our pull request best practices.

After submitting this PR, provide your team lead with access to your forked repository which allows them to run your branch in a Codespace.

Consider using GitHub’s draft pull request feature if requesting feedback on work-in-progress.

Notify collaborators

After opening your PR, you’ll want to:

• Notify your team lead and any SMEs or collaborators in Cyans that your PR is ready
• Change the status of your Team HQ task to Review and assign the task to the project owner

Celebrate!

Upon a successful PR review, the project maintainer will merge your changes into the main branch of the source repository and deploy the changes!

Hooray! You have successfully contributed technical documentation to LinkORB!