rhdh-feature-docs

Files (12)

• SKILL.md
• openai.yaml · agents/
• acli-setup.md · references/
• doc-structure-template.md · references/
• release-notes-guide.md · references/
• rhdh-docs-structure.md · references/
• techdocs-template.md · references/
• usage-examples.md · references/
• README.md · scripts/
• fetch_rhdh_docs.py · scripts/
• jira_acli.py · scripts/
• setup_acli.py · scripts/

SKILL.md (first lines)

# RHDH Feature Documentation Generator

This skill generates **actual documentation content** for Red Hat Developer Hub (RHDH) features in AsciiDoc format, following the RHDH documentation repository structure. It analyzes Jira features, linked PRs, and existing documentation to produce ready-to-use documentation files or specific updates to existing docs.

## When to Use This Skill

Use this skill when:
- A user provides a Jira feature/issue link from `redhat.atlassian.net` and wants **documentation content generated**
- Someone asks to "document this feature" or "write docs for" an RHDH feature
- You need to **generate actual documentation updates** to existing RHDH docs (not just analysis)
- A feature owner wants **ready-to-use AsciiDoc documentation** for their feature
- Documentation team needs **actual documentation content** following RHDH structure

**What this skill produces:**
- ✅ **Actual AsciiDoc documentation files** ready for RHDH docs repository
- ✅ **Specific updates/diffs** to existing documentation (what to change, where)
- ✅ **Release notes content** (ready to publish)
- ✅ **TechDocs content** (mkdocs.yml + markdown files for Backstage plugins)

**What this skill does NOT produce:**
- ❌ Meta-documents about documentation planning
- ❌ Project management documents about doc work
- ❌ Analysis reports without actionable documentation content

## Prerequisites

### Required Tools

1. **acli (Atlassian CLI)**
   - Download from: https://bobswift.atlassian.net/wiki/spaces/ACLI/overview
   - Verify installation: `acli --version`

2. **Jira Authentication**
   - Create API token: https://id.atlassian.com/manage-profile/security/api-tokens
   - Authenticate acli:
     ```bash
     acli jira auth login --site redhat.atlassian.net --email <your-email> --token
     ```
   - Verify: `acli jira project list --recent 1`

3. **Validation**
   - Run the setup script to verify everything is configured:
     ```bash
     python3 "$SKILL/scripts/setup_acli.py"
     ```
   - All checks should pass before using the skill

For detailed installation, authentication, OS-keyring, and troubleshooting steps,
read `references/acli-setup.md`.

### Optional Tools

- `gh` CLI for enhanced GitHub PR analysis
- Python 3.7+ available on `PATH` (the `jira_acli.py`, `fetch_rhdh_docs.py`, and `setup_acli.py` scripts use only the standard library)

## Output Modes

The skill generates **actual documentation content** in different formats based on the request:

### 1. RHDH Product Documentation (Default - AsciiDoc)
**User says:** "Document this feature", "Write docs for RHDHPLAN-1234", "Generate documentation for this"  

**What you generate:**
- **NEW feature:** Complete AsciiDoc documentation following RHDH structure
  - Master file (assembly)
  - Concept modules (con-*.adoc)
  - Procedure modules (proc-*.adoc)
  - Reference modules (ref-*.adoc)
  - Proper attributes, cross-references, includes
  
- **EXISTING feature:** Specific updates to existing docs
  - Which files to update
  - Exact sections to add/modify (with AsciiDoc content)
  - New modules to create (full content)
  - Updated cross-references

**Output format:** Ready-to-commit AsciiDoc files following RHDH docs repo structure

### 2. Release Notes Content
**User says:** "Generate release notes for...", "What's the release note for...", "Write release notes for RHDHPLAN-1234"  

**What you generate:**
- Release note type classification (Feature, Enhancement, Bug Fix, etc.)
- User-facing title (5-10 words)
- Description (1-3 paragraphs, ready to publish)
- Action required section (if applicable)
- Migration/upgrade notes (for breaking changes)

**Output format:** Markdown or AsciiDoc release notes content (ready to paste into release notes file)

### 3. TechDocs (Backstage Plugin Documentation - Markdown)
**User says:** "Generate tech docs for...", "Create techdocs for...", "Generate backstage docs for..."  

**First ask for the existing plugin TechDocs directory** (see Step 0). If it
exists, **update** those docs for this feature. If it does not exist, **create**
TechDocs for the whole plugin the feature builds on — not just this feature.

**What you generate:**
- `mkdocs.yml` configuration
- Complete Markdown documentation files:
  - `docs/index.md`
  - `docs/installation.md`
  - `docs/configuration.md`
  - `docs/usage.md`
  - Additional files as needed (api.md, troubleshooting.md, migration.md)

**Output format:** Complete TechDocs structure ready to copy to plugin repository

### 4. Documentation Update Summary (Analysis Mode)
**User says:** "What docs need updating for...", "Analyze documentation needs for...", "What documentation is required for..."  

**What you generate:**
- Which existing docs need updates (with file paths)
- What new documentation is needed
- Gaps in current documentation
- Recommended structure
- **But NO actual documentation content** - this mode is for analysis only

**Output format:** Markdown summary of documentation requirements

From redhat-developer/rhdh-skills, Apache-2.0.

More from redhat-developer/rhdh-skills