Documentation guide

Welcome to the Infrahub documentation guide. This document aims to answer any questions that may come up when creating or updating documentation.

Working with the docs site locally

The recommended way to run and build the docs locally is with Infrahub's suite of invoke-driven tasks. To run the commands, you should:

1. Install python.
2. Install invoke.
3. Install poetry.
4. Run poetry install from the Infrahub project directory.
5. Install Node.js (and npm).

Once these requirements are met, you'll have access to the doc task list.

invoke -l docs

The primary commands are as follows:

• invoke docs.install: Install the documentation dependencies via npm.
• invoke docs.build: Build the documentation website.
• invoke docs.generate: Generate source-derived documentation pages (such as the schema and Jinja templates).
• invoke docs.serve: Run a local development server for the documentation website.
• invoke docs.validate: Validate that the generated documentation has been committed to git.

Linting and automation

Infrahub uses Vale to check grammar, style, and word usage. You can find Vale's configuration in .vale.ini, and the Infrahub styles located in .vale/styles/Infrahub.

Markdownlint is used to encourage consistent markdown files, and Infrahub's configuration is located at .markdownlint.yaml.

Most Vale warnings match up with the style guide explanations below. Other warnings often fall into the Infrahub.spelling rule. These are caused by misspellings, product names, names of people, or otherwise unknown technical terms. See the procedures for updating rules below for details on adding terms to the approved list.

Install linters locally

The preferred way to work on the documentation with Vale and markdownlint is directly in an editor. Install the Vale and markdownlint VS Code plugins to enable in-editor warnings.

Disabling Vale and markdownlint

You can disable Vale and markdownlint in-line with the following markdown comments:

<!-- vale off -->
Ignored Specialized Phrase ignored by vale
<!-- vale on -->

<!-- markdownlint-disable -->
## Ignored markdown line
<!-- markdownlint-restore -->

This is useful in situations where specific style choices or markdown quirks force the use of an otherwise conflicting rule. In general, it is better to update existing configurations or create new rules rather than disable scanning of individual files.

Creating new Vale rules

For questions regarding how to add to or update an existing rule, see the Vale styles documentation. A wealth of examples are also available in GitLab's vale configuration.

Spelling errors

If Vale warns of a spelling mistake and the word is valid, you can fix it by updating the spelling-exceptions.txt file in the .vale/styles/ directory. When adding a new term, update and alphabetize the list to make future scanning easier.

Common replacement words

Add common shorthand words and phrases that have better alternatives to the swap.yml rule. For example, repo becomes repository.

Add special case capitalization words to the branded-terms-case-swap.yml rule. For example, Github becomes GitHub.

Writing markdown

Pages are written in MDX, which is a superset of markdown or generated by the app source.

In addition, Docusaurus has its own markdown-inspired components. You'll often find reference links, panels, and snippets used throughout the Infrahub docs.

Markdown tips

Ensure proper newlines

Use two full returns between paragraphs (one empty line). This ensures a new paragraph is created.

Notification blocks

When writing documentation, it's essential to guide the reader's attention to specific types of information. Notification blocks are a powerful tool to achieve this, allowing you to highlight information based on its nature and importance. Here are the types of notification blocks and how to use them:

• Info: Use info blocks for additional, helpful information that isn't required to complete the task but offers more context or useful tips.

  > **Info**: This feature is available in version 2.1 and later.

• Success: Use success blocks to highlight expected outcomes and "status checks" to ensure the reader is on track with the guide. These blocks can reinforce the reader's progress and provide positive feedback.

  > **Success**: If you've followed the steps correctly, your installation should now be complete.

• Warning: Warning blocks should be used to highlight common errors or mistakes that may occur during the process. They serve as preventive measures to help the reader avoid potential pitfalls.

  > **Warning**: Ensure you've backed up your files before proceeding with this step to prevent data loss.

• Danger: Use danger blocks to highlight irreversible or breaking actions. These notifications are critical for steps that could significantly affect the system or data if mishandled.

  > **Danger**: This action will permanently delete your data and cannot be undone.

Incorporating these blocks into your documentation makes it more interactive and user-friendly, guiding the reader through different stages of their learning or implementation process with visual cues that emphasize the significance of each piece of information.

Organizing new pages

We organize all documentation into four categories: tutorials, guides, topics, and reference. This is heavily influenced by the Diátaxis framework. The goal is to maintain a more organized, understandable set of docs.

Here are questions to ask when deciding where to place a new document:

• Are you walking the user through a scenario? Select Tutorials.
• Are you providing steps to complete a specific task? Select Guides.
• Are you providing background information, explanation, or abstract concepts? Select Topics.
• Are you providing APIs, command references, or concise reference information? Select Reference.

If you're unsure where something goes, diátaxis offers a map and compass to help.

When creating a new page in the documentation, in addition to creating the .mdx file containing the documentation itself, you must also add the page to the relvant section of the sidebars.ts file.

Tutorials

Tutorials are an opportunity to guide users through a repeatable process. The purpose is to provide basic competence in Infrahub or a feature-set.

They should:

• Introduce the user to the end goal.
• Be repeatable by any user.
• Describe practical steps, rather than abstract concepts.
• Provide immediate results.

The "Getting started" tutorial is a good example, as it walks the user through a scripted scenario in a demo environment.

For a deeper dive into tutorials, refer to the diátaxis tutorials page.

Tutorials are complex learning endeavors. Before deciding if a tutorial is necessary, consider how you might update an existing tutorial or if a guide would be a better option.

Guides

Guides may seem like tutorials, but they are a shorter set of universal instructions that can apply to any user's task. The purpose is to teach how to perform a specific task.

Naming guideline: Describe the task that the guide describes, preferably in 2-5 words.

For example:

• Installing Infrahub
• Creating new devices
• How to invite collaborators

For a deeper dive into guides, refer to the diátaxis guides page.

Topics

Sometimes called explanations, topics offer additional context and rationale into the workings of Infrahub. They should answer the question: "how does X work?"

Naming guideline: Write the topic name, but not a sentence.

For example:

• Artifact
• User management and authentication

Begin by giving a one to two sentence description of the topic, then dive in deeper as needed.

For a deeper dive into topics, refer to the diátaxis explanations page.

Reference

Reference docs serve a single purpose. To provide quick, clear information when a user needs it. The intention is not that users read the reference, but instead they consult it as needed when working with Infrahub.

Naming guidelines: Mirror the code-level naming guidelines where possible. This makes it easier to connect docs to code quickly.

For a deeper dive into reference docs, refer to the diátaxis reference page.

Creating and updating application screenshots

To ensure that Infrahub's screenshots remain up to date and to check that our guides work properly, we use end-to-end (e2e) tests. You'll find the e2e tests specifically designed for tutorials located in frontend/tests/e2e/tutorial.

To add a new screenshot in the documentation, use this command within the tutorial e2e test:

await saveScreenshotForDocs(page, "my-screenshot-name");

To update all documentation screenshots, run:

cd frontend/app
npm run test:e2e:screenshots

The screenshots will be saved in docs/docs/media. You can then use them in our documentation:

![optional caption](../../media/my-screenshot-name.png)

Style guide

As a general rule, prefer consistency and simplicity when possible. This guide should help in making choices, but it is a living document and should evolve as the needs of the project evolve. For anything not answered below, reference the Microsoft Style Guide.

General tips:

• Avoid words like easy, just, or simple to describe how to do something or how "easy" a task is.

• If a sentence looks too long, it probably is. Try and simplify it or break it into multiple sentences.
• Avoid jargon unless you are sure the reader knows the term.
• Don't hesitate to link between pages and concepts.
• Avoid repeating information when possible, and instead link out to topic or reference pages.

Language

We use American English for most standard text. Unique technical terms are included below, or in the Microsoft A-Z word list.

Trailing commas

Use a trailing comma when listing multiple items. This is commonly known as the Oxford comma or serial comma.

❌ Don't do this: There are devices, organizations and users.

✅ Do this: There are devices, organizations, and users.

Headings and titles

Headings and titles should capitalize the first word only and end with no punctuation. The exception being any proper noun.

❌ Don't do this: Getting Started!

✅ Do this: Getting started

Every page should have a top-level heading. Additional heading tiers can only exist if a higher tier has been used.

❌ Don't do this:

<!-- This is missing an h2 -->
# Page title

### Smaller heading

Avoid over-capitalization

It is tempting to want to capitalize all feature names. Unless the term is a named marketing feature, avoid capitalization.

❌ Don't do this: Git Repository, API Server, User Management

✅ Do this: Git repository, API server, user management

Lists

Capitalize the first letter of each list item. If an item is a complete sentence, give it a period at the end. If it's not, it is okay to omit punctuation. The Microsoft Style Guide has a good explanation of how to handle list punctuation.

When listing items and descriptions, prefer the use of a colon (:) instead of a dash (-).

<!-- Don't do this -->
- Not - this
- Or - this

<!-- Do this -->
- Do: this
- And: this

Colons

Avoid extra spaces before a colon.

<!-- Don't do this -->
Feature : Explanation of feature

<!-- Do this -->

Feature: Explanation of feature

Code blocks

When creating a code block or snippet with three backticks, make sure to include a language designation.

```bash
this is a shell script
```

Marking code items

Sometimes you need to mention a function or ModelName. To do so, use the inline code backticks in markdown.

Use i.e. for examples

Prefer i.e. over e.g. or ex.. In a sentence, i.e. is surrounded by commas.

For example: Select the current branch, i.e., 'main'.

It's also acceptable and clearer to use "for example" or "such as".

Common external words

Refer to external brand guidelines for capitalization rules. Here are some common spellings and uses for brands found in the Infrahub docs. Additional terms can be found in .vale/styles/Infrahub/branded-terms-case-swap.yml.

• GitHub
• GitLab
• Git
• RabbitMQ
• GraphQL
• MacOS
• Linux

Documentation release checklist

Before publishing new changes to documentation, complete the following tasks:

• Generate output files for automated pages with invoke docs.generate.
  • Confirm build of infrahubctl pages.
  • Confirm build of infrahub-cli pages.
  • Confirm build of schema pages.
• Generate application screenshots.
• If there is a new app version, create a new release notes document in docs/release-notes.
• Run linters and fix valid errors on all source files.
• Perform test build of docs, invoke docs.build.