Technical Documentation Style Guide

This style guide provides guidelines for creating technical documentation for our Next.js/TypeScript/React monorepo using Docusaurus.

Guidelines For New Documentation Pages

---

Outer Structure

Choose the location

Am I in the right place in the hierarchy?
Do I need to create a new hierarchy?

A New Page Hierarchy

In Docusaurus, a new page hierarchy is simply a directory. The name of the directory should be Pascal case. Each folder has an images directory for storing any local images and a _category_.json file which defines the label used in the sidebar, the position in the sidebar, and some metadata.

Choose from the set of pre-defined templates

You don't have to use one of the existing templates, but it may speed things up: The Templates Directory

All pages require front matter

All pages require front matter. Front matter is a bit of YAML cataloguing metadata. It is not visible in the rendered page, but you can see it in the source code at the top of each page. For example, the front matter for this page looks something like this:

---
title: "Style Guide"
description: "Our documentation style guide"
sidebar_position: 1
---

The title element will be what appears in the rendered sidebar. sidebar_position is the position in the left hand sidebar.

The filename

Use kebab-case for file names: user-authentication.md. The filename you choose for your documentation page isn't that important but try to make it descriptive.

---

Inner Structure

Page Organization

Every documentation page should follow this structure:

1. Front Matter - YAML metadata block
2. Page Title - Clear, descriptive, action-oriented
3. Brief Introduction - 1-2 sentences explaining the page's purpose
4. Main Content - Organized in logical sections

Example:

---
title: "Style Guide"
description: "The guide to total style"
sidebar_position: 1
---

# The Style Guide You Didn't Know You Needed

This page has all the details to make you a world-class style-maker. 

## How To Start Styling
...
### More Styling Details
...
## Moving To The Next Level
...

Use ## Markdown syntax for headings within a page

Markdown # headings roughly correspond to HTML H headings:

• H1 (#) - Page title
• H2 (##) - Main sections
• H3 (###) - Subsections
• H4 (####) - Sub-subsections
• H5 (#####) - Rarely used (consider restructuring if needed)
• H6 (######) - Very rarely used

Many special words should be enclosed in Markdown single back-ticks

Use backticks for:

• Function names: useState()
• Variable names: userProfile
• Inline code fragmens: replace var j = 1 with const j = 1
• File names: package.json
• Terminal commands: pnpm install
• URLs or pathnames: https://schwab.com/client-home or /api/users

Uncommon Acronyms Spelled Out On First Usage

• Spell out acronyms on first use: Class Variance Authority (CVA)
• Use the acronym thereafter: "Use CVA with Tailwind when appropriate"
• Common tech acronyms don't need spelling out: HTML, CSS, API, REST, JSON. API

Technology Name Standards

Use these exact spellings and capitalizations:

Technology	Correct Format	Incorrect
Next.js	Next.js or NextJS	Nextjs, next.js
TypeScript	TypeScript or Typescript	typescript
JavaScript	JavaScript or Javascript	javascript
React	React	react, ReactJS
Tailwind CSS	Tailwind	TailwindCSS, tailwind
Class Variance Authority	CVA	cva, class-variance-authority
Zod	Zod	ZOD, zod
pnpm	pnpm	PNPM, Pnpm
Visual Studio Code	VSCode or VS Code	vscode
GitHub	Github or GitHub	github

Emphasis and Admonitions

Use Docusaurus admonitions for important information. Five types are available. See the Emphasis Examples page for examples and code.

:::note
General notes and supplementary information
:::

:::tip[Pro Tip]
Use TypeScript strict mode for better type safety.
:::

:::info[Additional Context] 
Provides extra context or details about the topic.
:::

:::warning[Important]
Always validate user input with Zod schemas.
:::

:::danger[Security]
Never expose environment variables to the client.
:::

Use Code Blocks For Code

Docusaurus code blocks support syntax highlighting for nearly every language and include both copy and word-wrap buttons (hover your cursor over the upper right-hand corner to see the buttons). The Code Block Examples page has all the details. Here's a typical example:

Unit Test Example

import Button from '#components/Button';

describe('Button > Render', (): void => {
  test(`button renders provided attributes`, (): void => {

    const props = new ButtonFactory().mock();

    expect(element).toBeInTheDocument();
  });

Code:

```typescript showLineNumbers title="Unit Test Example"
import Button from '#components/Button';

describe('Button > Render', (): void => {
  test(`button renders provided attributes`, (): void => {

    const props = new ButtonFactory().mock();

    expect(element).toBeInTheDocument();
  });
``` 

Rules For Linking

Within a Page (Internal Anchors)

All headings can be referred to using anchor URLs. Use lowercase, kebab-case anchors:

<!-- Note that "Installation Process" becomes the anchor "installation-process" -->
## Installation Process
[Jump to installation](#installation-process)

Linking To Another Docusaurus Page

Linking from a page in a top-level docs directory (top-level directories are onboarding, technical, architecture, and docstyle) to another page in the same top-level directory

<!-- From any page to another page in the same docs directory -->
[Feature Flags](./feature-flag-arch.md)
[Style Guide](../styleguide.md)
[Testing Page](../../test.md#how-to-test)

Linking from a page in a top-level docs directory (top-level directories are onboarding, technical, architecture, and docstyle) to another page in a different top-level directory

<!-- Link placed in a document in the technical directory hierarchy. -->
<!-- Here, it refers to a document in the architecture hierarchy. -->
<!-- You have to include versioning (the word "current") and leave off the ".md" -->
[Architecture Caching](/architecture/current/caching-arch) 
<!-- Also placed in the technical directory hierarchy -->
[Mermaid Charts](/docstyle/current/mermaid-examples#flowcharts)

Linking To External Pages

You have two choices:

• Use markdown syntax which is simple:

[Next.js Documentation](https://nextjs.org/docs/)

• Use HTML <a> tag so that you can guarantee it opens in a new tab or window:

<a href="https://nextjs.org/docs/" target="_blank">Next.js Documentation</a>

General Linking Guidelines

Link text should be descriptive:

<!-- Good -->
[View the complete API reference](../technical/api-reference.md)
[Learn about component architecture](./component-patterns.md)

<!-- Avoid -->
[Click here](../technical/api-reference.md)
[Read more](./component-patterns.md)

Rules For Adding Attachments

Attachments must be put in the static/img/attachments directory. They can be referred to using this syntax in your documentation:

 <a href="/attachments/all-unit-tests.pdf" download="all-unit-tests.pdf" title="Unit Tests PDF Download">Unit Tests PDF Download</a>

Tables And Charts

Tables

Use Markdown syntax for tables if possible. If you need advanced formatting, use HTML. You can see table examples here: Table Examples

Diagrams And Charts

You can use PNG or JPG files that have been generated elsewhere. Put them into the nearest images directory (every directory should have an images directory) and refer to them using standard Markdown syntax:

![Alt text description](./images/number1.png)

Instead of using PNG or JPG files for your diagrams, consider using the lightweight Mermaid diagramming language. You can see Mermaid examples here: Table Examples. Here's a Gantt chart created using mermaid:

Sample Gantt Chart Using Mermaid