> For the complete documentation index, see [llms.txt](https://docs.giize.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giize.com/product-docs/operations/gitbook-migration-plan.md).

# GitBook Migration Plan

This page defines how to publish `ticket-dashboard/docs/` into GitBook with a structure close to `docs.vngcloud.vn`.

## Target Shape

The closest practical match is:

* a strong landing page with product summary and entry points
* a left sidebar split by audience and task type
* shallow section depth for high-traffic pages
* compact reference pages with tables and endpoint blocks

For this repository, the recommended top navigation is:

1. `Getting Started`
2. `Feature Guides`
3. `API Reference`
4. `Operations`

## Proposed GitBook Information Architecture

### Space Title

`Ticket Dashboard`

### Space Description

`Internal operating guide and integration reference for Ticket Dashboard, Order Report, IT Portal, SDP, and staging APIs.`

### Primary Sections

* `Getting Started`
  * audience: new engineer, operator, reviewer
  * goal: explain what the system is and how to run it
* `Feature Guides`
  * audience: operators and feature owners
  * goal: explain real workflows end to end
* `API Reference`
  * audience: integration and backend engineers
  * goal: keep endpoint and entity reference easy to scan
* `Operations`
  * audience: maintainers
  * goal: capture MCP usage, rollout notes, and publishing conventions

## Mapping From Local Docs To GitBook

| Local page                            | GitBook placement             | Notes                                                |
| ------------------------------------- | ----------------------------- | ---------------------------------------------------- |
| `docs/README.md`                      | space home                    | home page with hero, quick links, and system summary |
| `docs/getting-started/*`              | getting started collection    | onboarding and architecture                          |
| `docs/feature-guides/*`               | feature guides collection     | operator-focused workflow docs                       |
| `docs/api-reference/it-portal-api.md` | API Reference / IT Portal API | preserve request/response examples                   |
| `docs/api-reference/sdp-api.md`       | API Reference / SDP API       | baseline for existing production integration         |
| `docs/api-reference/staging-*`        | API Reference / Staging       | split by use case instead of one oversized page      |
| `docs/operations/*`                   | Operations                    | internal maintenance and publishing notes            |

## Authoring Rules

To keep the space consistent:

* one page should answer one primary question
* prefer short intro, then tables, then examples
* use the same endpoint block format on all API pages
* keep raw investigation detail in `document/`, not in GitBook
* update `docs/` only after source notes are validated

## Page Pattern Recommendations

### Landing Page

Recommended blocks:

1. one-sentence product summary
2. quick links for `Quick Start`, `Architecture`, `Order Report`, `SDP API`, `Staging API`
3. system scope cards:
   * operator workflows
   * integrations
   * staging research
4. maintenance note pointing to Operations

### API Reference Pages

Recommended order:

1. purpose
2. authentication/session note
3. endpoint table
4. entity fields
5. behavior notes
6. known reuse in `ticket-dashboard`

### Feature Guides

Recommended order:

1. business purpose
2. trigger point in app
3. workflow steps
4. data dependencies
5. failure modes
6. related APIs

## How To Resemble `docs.vngcloud.vn`

What we can realistically match:

* strong left navigation with grouped sections
* concise landing pages instead of long raw markdown
* consistent section intros and quick-link blocks
* split reference pages instead of giant technical dumps

What will still differ unless we invest more:

* branded visuals, custom icons, and product cards
* top-level GitBook customization and theme polish
* reusable callout components and richer embeds

## Recommended Next Steps After GitBook MCP Is Connected

1. create or connect the GitBook space
2. import `docs/README.md` as the space home
3. import pages using `docs/SUMMARY.md` order
4. convert key overview pages into richer GitBook blocks
5. add a glossary page if non-engineering users will read the docs
6. decide whether staging pages should stay internal-only

## Content Gaps Worth Filling Later

* screenshots for Order Report and OpenVPN flows
* glossary for SDP and IT Portal terms
* error catalog for common integration failures
* environment matrix for local, staging, and production behavior