Skip to content

[task] Convert chatops.md guide to task-oriented how-to format #1475

Closed as not planned

Description

@github-actions

Objective

Refactor docs/src/content/docs/guides/chatops.md to follow the task-oriented how-to guide structure with clear prerequisites, steps, and expected outcomes.

Context

The scout report recommends that how-to guides should be focused on solving specific tasks with prerequisites listed upfront and clear step-by-step instructions. This is a pilot conversion to establish the pattern. Part of issue #1433.

Approach

Restructure the existing chatops guide to follow this template:

---
title: How to Build a ChatOps Bot
description: Create a workflow that responds to slash commands in issues and pull requests
---

## What You'll Build
A bot that responds to `/hello` commands in issue comments.

## Prerequisites
- Repository with GitHub Actions enabled
- Basic understanding of agentic workflows (complete "Your First Workflow" tutorial first)

## Steps

### 1. Create the Workflow File
Create `.github/workflows/chatops-bot.md` with this content:
[complete code example]

### 2. Test the Command
1. Open any issue in your repository
2. Add a comment with `/hello`
3. Wait 10-30 seconds

### 3. Verify the Response
You should see a comment from github-actions bot responding to your command.

## Expected Result
The bot responds to `/hello` commands with a greeting message.

## Troubleshooting
**Bot doesn't respond**: Check workflow run logs in Actions tab...

## Next Steps
- Learn how to add parameters to commands (link)
- Restrict bot to specific users (link)

## Related
- Tutorial: Your First Workflow
- Reference: Command Triggers

Files to Modify

  • docs/src/content/docs/guides/chatops.md

Writing Guidelines

  • Start with clear task statement ("How to...")
  • List prerequisites upfront
  • Use numbered steps
  • Include complete, working code examples
  • End with verification step
  • Add troubleshooting section for common issues
  • Link to related tutorials and reference docs

Acceptance Criteria

  • Title starts with "How to"
  • Prerequisites section exists
  • Steps are numbered and actionable
  • Code examples are complete and tested
  • Expected outcome is clearly described
  • Troubleshooting section included
  • Links to related documentation
  • Page builds without errors
    Related to Simplify docs scaffolding #1433

AI generated by Plan Command

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions