influxdata / influxdata/docs-v2
Reclassify example.md and create.md off the overloaded test_only flag
- 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