Skip to content

Conversation

Copy link
Contributor

Copilot AI commented Nov 22, 2025

The /docs folder contained 3 large markdown files (136, 695, 441 lines) that were becoming difficult to navigate and maintain.

Changes

  • Reorganized into topic-based structure: Split into 21 focused files across 3 directories (getting-started/, admin/, developer/)
  • Added navigation: Created README index files in each directory linking to relevant topics
  • Updated references: Modified README.md and backend/mcp/progress_updates_demo/QUICKSTART.md to point to new structure
  • Preserved history: Moved original files to docs/archive/ with explanation

New Structure

docs/
├── getting-started/
│   └── installation.md
├── admin/
│   ├── configuration.md
│   ├── mcp-servers.md
│   ├── llm-config.md
│   ├── authentication.md
│   ├── file-storage.md
│   ├── compliance.md
│   ├── tool-approval.md
│   ├── logging-monitoring.md
│   ├── admin-panel.md
│   ├── help-config.md
│   └── splash-config.md
└── developer/
    ├── architecture.md
    ├── conventions.md
    ├── creating-mcp-servers.md
    ├── working-with-files.md
    ├── progress-updates.md
    └── canvas-renderers.md

Average file size reduced from 424 lines to ~62 lines per topic.

Original prompt

This section details on the original issue you should resolve

<issue_title>Split up docs</issue_title>
<issue_description>The /docs folder's 3 .md files are becoming large and need to be broken up</issue_description>

Comments on the Issue (you are @copilot in this section)


💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Copilot AI and others added 2 commits November 22, 2025 03:40
- Created getting-started, admin, and developer directories
- Split 01_getting_started.md into installation.md
- Split 02_admin_guide.md into 10 focused topic files
- Split 03_developer_guide.md into 6 focused topic files
- Updated all references in README.md and QUICKSTART.md
- Each directory now has an index README.md for navigation

Co-authored-by: garland3 <1162675+garland3@users.noreply.github.com>
- Moved old doc files to docs/archive/
- Created archive/README.md explaining the reorganization
- All new documentation is properly organized and linked
- Total content preserved and enhanced with navigation

Co-authored-by: garland3 <1162675+garland3@users.noreply.github.com>
Copilot AI changed the title [WIP] Refactor docs by splitting large markdown files Split monolithic documentation files into topic-based structure Nov 22, 2025
Copilot AI requested a review from garland3 November 22, 2025 03:45
Copilot finished work on behalf of garland3 November 22, 2025 03:45
@garland3 garland3 marked this pull request as ready for review November 22, 2025 04:14
Copilot AI review requested due to automatic review settings November 22, 2025 04:14
@garland3 garland3 merged commit bd5114e into main Nov 22, 2025
2 checks passed
@garland3 garland3 deleted the copilot/split-up-docs-files branch November 22, 2025 04:15
Copilot finished reviewing on behalf of garland3 November 22, 2025 04:16
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR reorganizes the /docs folder from 3 large monolithic markdown files (totaling 1,272 lines) into a topic-based structure with 21 focused files across 3 directories. The reorganization improves documentation maintainability and navigation by reducing average file size from 424 lines to approximately 62 lines per topic.

Key Changes:

  • Split documentation into logical topic-based files organized by user role (getting-started, admin, developer)
  • Created navigation README files in each directory with links to relevant topics
  • Updated external references in README.md and backend/mcp/progress_updates_demo/QUICKSTART.md to point to the new structure
  • Moved original files to docs/archive/ with a clear explanation of the reorganization

Reviewed changes

Copilot reviewed 24 out of 27 changed files in this pull request and generated no comments.

Show a summary per file
File Description
docs/getting-started/installation.md Installation guide extracted from 01_getting_started.md with updated cross-references
docs/getting-started/README.md Navigation index for getting started documentation
docs/developer/working-with-files.md File storage guide extracted from 03_developer_guide.md
docs/developer/progress-updates.md Progress updates guide extracted from 03_developer_guide.md
docs/developer/creating-mcp-servers.md MCP server creation guide extracted from 03_developer_guide.md
docs/developer/conventions.md Development conventions extracted from 03_developer_guide.md
docs/developer/canvas-renderers.md Canvas customization guide extracted from 03_developer_guide.md
docs/developer/architecture.md Architecture overview extracted from 03_developer_guide.md
docs/developer/README.md Navigation index for developer documentation
docs/archive/README.md Explanation of documentation reorganization with links to new structure
docs/archive/03_developer_guide.md Original developer guide moved to archive
docs/archive/02_admin_guide.md Original admin guide moved to archive
docs/archive/01_getting_started.md Original getting started guide moved to archive
docs/admin/tool-approval.md Tool approval system guide extracted from 02_admin_guide.md
docs/admin/splash-config.md Splash screen configuration guide extracted from 02_admin_guide.md
docs/admin/mcp-servers.md MCP server configuration guide extracted from 02_admin_guide.md
docs/admin/logging-monitoring.md Logging and monitoring guide extracted from 02_admin_guide.md
docs/admin/llm-config.md LLM configuration guide extracted from 02_admin_guide.md
docs/admin/help-config.md Help modal customization guide extracted from 02_admin_guide.md
docs/admin/file-storage.md File storage configuration guide extracted from 02_admin_guide.md
docs/admin/configuration.md Configuration architecture guide extracted from 02_admin_guide.md
docs/admin/compliance.md Compliance and security guide extracted from 02_admin_guide.md
docs/admin/authentication.md Authentication and authorization guide extracted from 02_admin_guide.md
docs/admin/admin-panel.md Admin panel usage guide extracted from 02_admin_guide.md
docs/admin/README.md Navigation index for administrator documentation
backend/mcp/progress_updates_demo/QUICKSTART.md Updated reference from old to new documentation path
README.md Updated documentation links to point to new topic-based structure

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.

Split up docs

2 participants