Contribute to the docs

We welcome contributions to the Tiger Data documentation. Whether you’re reporting a typo, suggesting clearer wording, or adding a changelog entry, your feedback helps everyone. This page explains the main ways to contribute and what good looks like for each.

Ways to contribute

You can help improve the docs in three main ways:

• Open an issue: Share feedback, report problems, or suggest improvements without changing code.
• Submit a change via pull request (PR): Fix errors, improve clarity, or add content; your change goes through review and our PR checklist.
• Submit a changelog request: Propose a new entry for the changelog (for example, a new feature or release).

Each path has a template and expectations so maintainers can review quickly and keep the docs consistent. Below we walk through each option and give examples of strong contributions.

Open an issue for feedback

Use a GitHub issue when you want to:

• Report unclear, outdated, or incorrect documentation
• Suggest new topics or improvements without writing the change yourself
• Ask questions about how something is documented
• Flag broken links, missing steps, or confusing examples

Why we use issues: Issues create a visible record of feedback, allow discussion, and can be linked from PRs when someone implements a fix. They also help us prioritize and triage.

Choose the right issue template

In the Tiger Data Docs repository, we provide issue templates so your report has the right structure:

• Doc feedback/bug: For general documentation feedback, errors, or “this doesn’t match what I see” reports.
• Doc correction or change: When you’re planning to (or already) submit a PR and want to link an issue for context.
• Changelog request: When you want to propose a new changelog entry (for example, for a release or feature); the template reminds you of the required fields.

Using the template ensures we get the necessary context (page, section, and description) without back-and-forth.

Example of a good issue

Title: [Get started] Quickstart step 3 is missing the connection port

Body (using the doc feedback template):

• Page/section: Get started → Quickstart (5 minutes) → Step 3 “Connect to your service”
• What’s wrong: The example connection string doesn’t include the port. New users copy-paste and get a connection error.
• What you expected: Either include the port in the example or add a note that the port is required and where to find it in the console.
• Optional: “I can submit a PR with the fix if that helps.”

Why this is good: The maintainer knows exactly where to look, what’s wrong, and what would fix it. Offering a PR is optional but speeds things up.

Example of a weak issue

Title: Docs are wrong

Body: “The quickstart doesn’t work.”

Why it’s weak: We don’t know which page, which step, or what “doesn’t work” means (connection? copy-paste? wrong product?). That leads to follow-up questions and slower resolution.

Submit a change via pull request (PR)

When you’re ready to change the docs (fix a typo, clarify a sentence, add a step, or add new content), you do that via a pull request. All PRs must use the repository’s pull request template and pass the checklist before merge. This keeps quality consistent and makes review faster.

What the PR template requires

Every PR in this repo uses the template in .github/pull_request_template.md. You’ll see something like:

1. Describe your changes: What did you change and why?
2. Related Issues: If there’s an issue (e.g. “Fixes #123”), link it so the issue is closed when the PR is merged.
3. Checklist before requesting a review: A list of boxes you must check before asking for review (see below).

Filling this out is required. Our CI checks that the template sections are present and that the checklist is complete; incomplete PRs get a reminder comment.

Checklist before requesting a review

The template includes a checklist that you must complete before requesting review. In short:

• Confirm the PR is ready for review (or open as draft).
• Confirm the change has been deployed to a staging environment and you’ve reviewed the deployed version.
• Confirm content is technically accurate and free of typos/grammar errors.
• If you added or changed code, confirm it was tested on the latest available version.
• Confirm images/videos are clear and match production (or dev for unreleased features).
• Confirm the content matches current product behavior.
• Confirm all CI checks have passed.
• If the change references a feature that isn’t public yet, add a note so we can schedule the merge for after release.

Why we have this: Docs are read in production. Checking accuracy, staging, and visuals in one place reduces the chance of shipping mistakes and keeps the bar high.

Helpful resources before you edit

• README: Development quickstart, site structure, and how content is organized (e.g. get-started/, learn/, build/). Use this to find where your change belongs and how to run the site locally.
• Component usage (readme-component.md): How to use callouts (Tip, Note, Important, Warning, CTA), buttons, and other MDX components so your new or edited content matches existing style.
• Doc constants: The repo uses shared constants (e.g. for product/database names) in src/constants.ts. Use them in prose and headings (e.g. {C.PG}) instead of hardcoding names; the README explains how.

Following these keeps your PR consistent with the rest of the docs and avoids rework in review.

Example of a good PR

Title: Fix missing port in quickstart connection string

Describe your changes:

• Updated the connection string in “Connect to your service” to include the port (e.g. :5432).
• Added a one-line note that the port is shown in the Tiger Console connection details.
• Reason: Users were copy-pasting the string and hitting connection failures; including the port and a pointer to the console reduces support load and improves first-run success.

Related Issues: Issue #42

Checklist: All boxes checked. Author notes: “Verified on staging; connection string matches console. No new code, only prose and one example.”

Why this is good: Clear scope, linked issue, and checklist done. The description explains the “why,” which helps future readers and maintainers.

Example of a weak PR

• No description: “Fixed the doc.” Reviewers don’t know what was fixed or where.
• Checklist not completed: CI will comment and block merge until the template is filled and boxes are checked.
• New content that ignores components: e.g. using raw HTML or markdown that doesn’t use the project’s Callout/Button patterns; that leads to style inconsistencies and rework.

Submit a changelog request

The changelog is the place for product and doc updates (new features, improvements, releases). If you have information about a change that should be announced there but you’re not editing the repo yourself, you can submit a changelog request via an issue.

How changelog entries are added

Changelog entries live in a single file: src/content/docs/get-started/news/new.mdx. Each entry is structured with:

• A ## heading (for the right-hand “On this page” nav)
• A <ChangelogEntry> block with title, date (YYYY-MM-DD), and tags
• A heading slot (the visible card title) and body content (with at least one ### subsection)

The full format, allowed tags, and examples are documented in README-changelog.md. Maintainers use that guide when adding or editing entries.

Using the changelog request issue template

Open a changelog request (or when opening a new issue, choose “Changelog request”). The template will ask for:

• Title of the entry: Short, clear title for the new announcement.
• Date: When the change was or will be released (YYYY-MM-DD).
• Suggested tags: e.g. new-feature, improvement, bug-fix, breaking-change (from the allowed list in README-changelog.md).
• Summary / body: What’s new, for whom, and any links (docs, blog, etc.).

You don’t need to write MDX; just provide the information. A maintainer can turn it into a proper <ChangelogEntry> using README-changelog.md.

Example of a good changelog request

Title: Changelog request: Automated chunk tuning (beta)

Body:

• Entry title: Automated chunk tuning (beta)
• Date: 2026-03-06
• Tags: new-feature, beta
• Summary: Tiger Cloud now offers automated chunk tuning in beta. Users can enable it per hypertable in the Explorer. The tuner recommends chunk intervals even if they don’t enable auto-tuning. Changes are incremental and logged in the Activity log. Link to docs: improve-hypertable-performance.

Why this is good: We have a clear title, date, tags, and a concise summary that a maintainer can drop into the changelog file and format according to README-changelog.md.

Example of a weak changelog request

• Vague title: “New feature” with no product or feature name.
• Missing date or tags: We need both to add the entry correctly.
• No summary: “We released something” doesn’t give enough to write a useful card for readers.

Writing style

Punctuation

• Do not use the em dash (Unicode U+2014) in prose, frontmatter descriptions, tables, or comments. It is easy to confuse with hyphens or en dashes and it is not consistent across keyboards. Use commas, semicolons, colons, or parentheses instead, or split the thought into two sentences.
• For label + gloss patterns (for example in lists of links or options), use a colon after the label: **From CSV**: For comma-separated files… rather than an em dash between the label and the rest.

SEO summary in frontmatter

• description: Used by Starlight for <meta name="description">, Open Graph, and (in this site) subtitles in the sidebar and some nav UI. Use for pages where that short line should appear next to the title in navigation.
• seoDescription: Use when you want the same kind of one-line summary for search and social meta tags only. It is injected in src/components/Head.astro and does not populate the sidebar. Prefer description for normal docs pages; use seoDescription when the menu should show titles only.
• If both are set: description wins. Starlight keeps using description for meta and nav; seoDescription is ignored for meta injection so you do not get duplicate tags. Remove the extra field when you notice both, or leave it as a harmless no-op until cleanup.

Quick reference

Contribution type	Where to start	Key reference
Feedback/report a problem	Open doc feedback issue	doc-feedback.md
Doc correction (with or without PR)	Open doc correction issue	doc-correction-or-change.md
Fix or improve the docs	Fork, edit, then open a PR	PR template, README, readme-component.md
Propose a changelog entry	Open changelog request	README-changelog.md, changelog-request.md

Want to add the changelog entry yourself?

If you’re comfortable editing MDX, you can add the entry directly in src/content/docs/get-started/news/new.mdx and open a PR. Follow the structure and checklist in README-changelog.md so your entry matches existing ones and passes review.

Thank you for helping improve Tiger Data documentation.