elastic / elastic/ai-github-actions

[information-architecture] Public Watchdogs page advertises internal Downstream Health workflow

Open
#1,504 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
11
Forks
16
Avg merge
22h 9m
Merged PRs (30d)
31

Description

## Information Architecture Findings

### 1. Public Watchdogs onboarding points users to an internal-only workflow
**Area:** Grouping / Empty states and onboarding
**Component(s):** `docs/blog/posts/meet-the-watchdogs.md`, `docs/workflows/gh-agent-workflows.md`, `mkdocs.yml`, `gh-agent-workflows/README.md`, `gh-agent-workflows/internal-downstream-health/README.md`
**Problem:** The public Watchdogs blog post presents Downstream Health alongside the public Watchdog workflows, then tells users they can configure and deploy all of these agents from the GitHub Agent Workflows docs. However, the docs catalog and navigation do not expose Downstream Health, while the repository workflow index classifies it as an internal, unsupported workflow. A user following the public onboarding path is encouraged to look for an agent that is not available in the public docs, with no explanation that it is internal-only.

Evidence:
- `docs/blog/posts/meet-the-watchdogs.md:37-39` introduces **Downstream Health** as one of the Watchdog agents.
- `docs/blog/posts/meet-the-watchdogs.md:47-49` says all of these Watchdog agents can be configured and deployed using the GitHub Agent Workflows documentation.
- `docs/workflows/gh-agent-workflows.md:84-99` lists the standalone scheduled workflows exposed in the public workflow catalog, but omits Downstream Health.
- `mkdocs.yml:61-80` exposes Planning & Insights, Base, Advanced, and Elastic-specific workflow nav groups, but no Downstream Health entry.
- `gh-agent-workflows/README.md:92-96` places Downstream Health under **Internal Workflows** and says those workflows are for internal use and not officially supported.
- `gh-agent-workflows/internal-downstream-health/README.md:1-17` still contains a quick install path for the internal workflow, so the missing public docs distinction is not because the workflow lacks setup material.

**Suggested improvement:** Either remove Downstream Health from the public Watchdogs post, or add a clearly labeled internal/unsupported section in the public workflow catalog and navigation so users understand why it differs from the other Watchdog agents before they try to configure it.

## Suggested Actions
- [ ] Decide whether Downstream Health should be public-facing or internal-only.
- [ ] If internal-only, remove it from `docs/blog/posts/meet-the-watchdogs.md` or label it as internal there.
- [ ] If it should be discoverable, add a clearly labeled internal/unsupported entry to the workflow catalog and docs navigation.

---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Information Architecture](https://github.com/elastic/ai-github-actions/actions/runs/28675318239)

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

Contributor guide

Open the contributing guide

Research direction

Read the cited sections in docs/blog/posts/meet-the-watchdogs.md, docs/workflows/gh-agent-workflows.md, mkdocs.yml, gh-agent-workflows/README.md, and gh-agent-workflows/internal-downstream-health/README.md. Confirm whether Downstream Health is internal-only, then align the public post, workflow catalog, and navigation with that decision. Done means users can tell whether it is available and supported without following an ambiguous onboarding path.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, markdown, yaml
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.