-
Notifications
You must be signed in to change notification settings - Fork 45
Closed
Labels
ai-generateddocumentationImprovements or additions to documentationImprovements or additions to documentationplan
Description
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
- 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.- 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))
:::- 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.- Consider adding a glossary page at
/docs/src/content/docs/reference/glossary.mdx
Files to Modify
docs/src/content/docs/index.mdx- Improve "agentic" definitiondocs/src/content/docs/setup/quick-start.mdx- Add YAML and frontmatter explanationsdocs/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
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
ai-generateddocumentationImprovements or additions to documentationImprovements or additions to documentationplan