influxdata / influxdata/docs-v2

Reclassify example.md and create.md off the overloaded test_only flag

Open
#7,266 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
JavaScript
Stars
82
Forks
326
Avg merge
1d 1h
Merged PRs (30d)
82

Description

## Goal

`test_only: true` is currently overloaded to mean three different things: regression test fixtures, a contributor-facing shortcode showcase, and contributor documentation. Two pages use the flag as a crude "keep out of production" lever but are **not** test fixtures and need proper classification.

Surfaced while scoping #7241 (which fixes `/__tests__/` fixtures only). Parent epic: #7230 (Phase 0).

## Pages to reclassify

- **`content/example.md`** (`/example/`) — the browsable shortcode **showcase**, linked from `README.md`, `DOCS-CONTRIBUTING.md`, `DOCS-SHORTCODES.md`, and exercised by `test:shortcode-examples` and `render-regression.cy.js`. Fixture-adjacent but contributor-facing. Decide: move under `__tests__` (and update the ~7 references + redirect `/example/`), or give it a stable contributor home.
- **`content/create.md`** (`/create/`) — contributor **documentation** for the `docs` CLI (added in e8a48e3). Not a test. Options: publish under a real contributor path (e.g. `/contribute/`), fold into `DOCS-CONTRIBUTING.md`, or keep unpublished via a clearer mechanism than `test_only`.

## Context

After #7241, the convention is: **test fixtures live under `__tests__/`, and `__tests__/` never ships to production** (via a `render: never` cascade in `config/production/`). These two pages don't fit that convention and shouldn't be swept under `__tests__`.

## Acceptance criteria

- `example.md` and `create.md` no longer rely on `test_only` purely as a production-visibility hack
- Each has a deliberate home: published at a stable URL, or intentionally excluded with a mechanism that matches its actual category
- References (docs links, npm scripts, Cypress specs) updated to match
- Once both are resolved, a structural guard can assert "every `test_only: true` page lives under `__tests__/`"

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with content/example.md and content/create.md, then trace the README.md, DOCS-CONTRIBUTING.md, DOCS-SHORTCODES.md, npm scripts, and render-regression.cy.js references named in the issue. Compare their current test_only behavior with the production render: never convention and decide a deliberate home or exclusion mechanism for each page. Done means references and URLs are consistent, neither page relies on test_only as a visibility hack, and the stated structural guard could pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
cypress, javascript
Domain
documentation, testing-qa
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.