Skip to content

Organize references by domain and normalize legacy docs - #11

Merged
antonflor merged 1 commit into
mainfrom
agent/organize-docs-by-domain
Jul 19, 2026
Merged

Organize references by domain and normalize legacy docs#11
antonflor merged 1 commit into
mainfrom
agent/organize-docs-by-domain

Conversation

@antonflor

Copy link
Copy Markdown
Owner

What changed

  • Moved all reference pages into a shallow docs/<domain>/<topic>.md hierarchy across networking, network platforms, Cisco contact center, cloud, containers, automation, Linux, high availability, and development.
  • Kept project-level files (README.md, CONTRIBUTING.md, STYLE_GUIDE.md, and LICENSE) at the repository root.
  • Added and documented a filename convention based on the canonical name engineers actually search for:
    • common, unambiguous acronyms stay short (tcp.md, ospf.md, lldp.md);
    • ambiguous concepts stay descriptive (spanning-tree.md, osi-model.md);
    • vendor references name the platform (arista-eos.md, cisco-ios.md, fortigate.md, junos.md);
    • domain-specific product acronyms omit redundant prefixes (cuic.md, cvp.md, icm.md).
  • Rewrote visibly outdated or malformed legacy pages for Clos, LLDP, OSI, TCP, UDP, awk, sed, regex, SCP, and Corosync.
  • Replaced the old Cisco CUIC/CVP/ICM pages with concise, version-sensitive legacy references that explicitly state technical validation is pending.
  • Updated visual-guide links, contributor guidance, and the root index for every moved or renamed page.
  • Reworked CI to discover every docs/**/*.md page automatically, enforce the shallow domain layout, reject topic Markdown at the root, require true H1 document titles, validate Mermaid blocks, and check internal links.

Why

The repository had outgrown a flat root-level collection. The README provided categories, but the filesystem did not. Several inherited pages also predated the current style guide and used heading level 3 as their document title, lacked honest validation status, or contained generic and stale prose.

Validation

  • Built the restructure as one Git tree and one commit so unchanged pages retain their original blobs and GitHub can detect clean renames.
  • Updated every index and visual-guide link alongside the moves.
  • GitHub Actions will validate the resulting folder structure, H1 titles, Mermaid fences, and internal links before merge.

@antonflor
antonflor merged commit 424f777 into main Jul 19, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant