Skip to content

[plan] Add glossary definitions for technical jargon #6509

@github-actions

Description

@github-actions

Objective

Add clear definitions for technical terms ("agentic", "frontmatter", "YAML", "safe outputs") on first use throughout the documentation.

Problem

Terms like "agentic", "frontmatter", and "YAML" are used throughout the docs without definition, assuming prior knowledge. The explanation of "agentic" uses the word to define itself, and YAML syntax is shown without explaining what YAML is.

Approach

  1. Improve the "agentic" definition on the homepage to be self-explanatory:
**Agentic means the AI can think and decide for itself.** Unlike traditional automation that follows exact steps you program, agentic workflows give the AI a goal and let it figure out how to achieve it—like asking a smart assistant to "organize my issues" instead of writing code for every possible scenario.
  1. Add a YAML basics callout in the Quick Start guide:
:::tip[YAML Basics for Beginners]
The configuration section uses YAML syntax:
- `key: value` — Sets a configuration option
- `- item` — Creates a list item
- Indentation matters (use 2 spaces, not tabs)
- Learn more: [YAML Tutorial]((redacted))
:::
  1. Add frontmatter explanation where first mentioned:
**Frontmatter** is a section at the top of a markdown file (between `---` markers) that contains configuration in YAML format. It's commonly used in static site generators and documentation tools.
  1. Consider adding a glossary page at /docs/src/content/docs/reference/glossary.mdx

Files to Modify

  • docs/src/content/docs/index.mdx - Improve "agentic" definition
  • docs/src/content/docs/setup/quick-start.mdx - Add YAML and frontmatter explanations
  • docs/src/content/docs/reference/glossary.mdx - Create glossary page (optional)

Acceptance Criteria

  • "Agentic" explained without using the word to define itself
  • YAML basics callout added before first YAML example
  • Frontmatter defined on first use
  • Safe outputs explanation improved with security context
  • Definitions use beginner-friendly language
  • No assumed prior knowledge

Reference

From noob test report: Confusing Areas #1, #2, #3, #4
Related to #6505

AI generated by Plan Command for discussion #6502

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions