elastic / elastic/ai-github-actions

[information-architecture] Developing page links break docs-site navigation flow

Open
#1,165 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. Top-level **Developing** page routes users out of docs-site navigation
**Area:** Navigation
**Component(s):** `mkdocs.yml`, `docs/developing.md`
**Problem:** The docs navigation presents **Developing** as a first-class destination, but its core architecture links immediately send users to GitHub blob pages instead of in-site docs routes. This breaks navigation continuity at a top-level node and forces users to re-orient outside the docs IA.

**Evidence:**
- `mkdocs.yml:84` includes `Developing: developing.md` in the main docs nav.
- `docs/developing.md:7-9` points the key "Docs" links to external GitHub URLs (`.../gh-agent-workflows/DEVELOPING.md` and `.../claude-workflows/DEVELOPING.md`) rather than docs-site pages.

**Suggested improvement:** Publish or map workflow-specific development guides into docs-site routes, then update `docs/developing.md` to use internal links so users can continue navigating within the docs structure.

## Suggested Actions
- [ ] Add internal docs pages/routes for workflow-specific development guides currently linked as GitHub blobs.
- [ ] Replace external blob links in `docs/developing.md` with internal docs links.
- [ ] Ensure top-level nav destinations keep users inside docs-site navigation whenever equivalent internal content exists.

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

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.