elastic / elastic/ai-github-actions
[information-architecture] Developing page links break docs-site navigation flow
- 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
Assessment
This issue has not been assessed yet.