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

No one assigned

    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