videojs/v10

Docs: Audit Subtitle/Opening Paragraph Redundancy Across Docs

Open

#1,062 opened on Mar 20, 2026

View on GitHub
 (6 comments) (0 reactions) (0 assignees)TypeScript (67 forks)github user discovery
docsgood first issuesite

Repository metrics

Stars
 (804 stars)
PR merge metrics
 (PR metrics pending)

Description

[!NOTE] Triage estimate — cycle priority and story points were assigned during an AI-assisted planning pass and are rough first guesses. Confirm or adjust when you pick this up.

Context

Several docs pages have a description subtitle and an opening paragraph that do the same work. The subtitle doesn't add value when the first sentence restates it.

Feedback from @davekiss:

There are several moments in the docs where I feel that the page, subheader, and the first sentences on the page are basically doing the same work. They're describing the same thing. It makes it feel like the subheader doesn't really have much of a purpose, and you might be better off considering removing it, only keeping it for SEO purposes in meta tags. We face this too on the Mux docs sometimes, just a thought. Alternatively revisit the first sentences so it's doing different work than the subheadline.

Proposal

Audit docs pages and either:

  • Differentiate the opening paragraph from the subtitle so each does distinct work, or
  • Hide the subtitle visually and keep it only in meta tags for SEO

Contributor guide

Research direction
Audit documentation pages to identify instances where the subtitle and opening paragraph convey the same information. Then propose either revising the opening paragraph to provide additional context or hiding the subtitle visually while keeping it in meta tags for SEO.
Tech stack
None
Domain
documentation
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
GitBasic understanding of HTML/CSS for meta tags
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
80