Skip to content

Add contextual descriptions to specialized guides explaining when they're needed #1141

@naomi-freecodecamp

Description

@naomi-freecodecamp

Description

I'd like to propose adding brief introductory descriptions to the specialized documentation pages (like "Work on Playwright tests", "Work on mobile app", etc.) that explain when a contributor actually needs to reference that guide.

Problem Statement

Currently, specialized guides jump straight into technical content without explaining the context of when a contributor would need them. New contributors may:

  • Feel overwhelmed thinking they need to read everything
  • Not realize a guide is relevant to their specific contribution
  • Waste time reading documentation that doesn't apply to their work

Proposed Solution

Add a short introductory section at the top of each specialized guide that answers:

  • When do I need this? - What types of contributions require this knowledge
  • Can I skip this? - Reassurance that not every contributor needs every guide

Example

For "Work on Playwright tests":

You'll need this guide if you're adding or modifying end-to-end tests, or if your contribution changes user-facing behavior that requires test coverage. If you're only fixing a typo or updating documentation, you can skip this guide.

Pages That Would Benefit

  • Work on Playwright tests
  • Work on mobile app
  • Work on documentation
  • Work on practice projects
  • Any other specialized workflow guides

Benefits

  • Reduces contributor overwhelm
  • Helps contributors find relevant documentation faster
  • Makes the contribution process feel more approachable
  • Clarifies the scope of each guide upfront

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions