Add scenario-based documentation with decision flowchart
- Ngôn ngữ chính
- TypeScript
- Star
- 26
- Fork
- 9
- Merge trung bình
- 1 ngày 3 giờ
- Pull request đã merge (30 ngày)
- 20
Mô tả
## Summary
Create scenario-level documentation that guides users through key decisions (branching strategy, source of truth, environment topology, etc.) via a decision flowchart, landing them in the appropriate "how-to" doc for their chosen setup.
## Problem
Users come to APIOps CLI with different organizational constraints and preferences. Currently, they must read through all documentation to figure out which setup applies to them. A guided decision tree would dramatically reduce time-to-value.
## Proposed Content
### Decision Flowchart
A visual flowchart (mermaid diagram or similar) that walks users through key decisions:
1. **Source of Truth** — Is APIM the source of truth, or is the Git repo?
2. **Branching Strategy** — Trunk-based, GitFlow, environment branches, etc.
3. **Environment Topology** — One APIM instance per environment, or multiple environments on a single instance?
4. **CI/CD Platform** — GitHub Actions or Azure DevOps?
5. **Change Flow** — Portal-first (extract → commit → promote) or code-first (edit → PR → publish)?
### Scenario Landing Pages
Each leaf of the decision tree links to a dedicated "how-to" page covering:
- Recommended repo structure
- Configuration file setup (filters, overrides)
- CI/CD pipeline configuration
- Step-by-step walkthrough for the chosen scenario
- Common pitfalls and FAQ
### Example Scenarios
- **Scenario A**: Git as source of truth, trunk-based development, separate APIM per environment, GitHub Actions
- **Scenario B**: Portal-first, feature branches, single APIM instance, Azure DevOps
- **Scenario C**: Hybrid (portal for discovery, Git for promotion), environment branches
## Acceptance Criteria
- [ ] Decision flowchart is created and embedded in documentation
- [ ] At least 3 scenario landing pages are written
- [ ] Each scenario page includes repo structure, config setup, and CI/CD guidance
- [ ] Flowchart is maintained as a mermaid diagram (or similar) for easy updates
- [ ] Documentation index/nav links to the scenario guide prominently
Hướng dẫn đóng góp
Hướng nghiên cứu
Bắt đầu bằng cách xem xét cấu trúc và điều hướng tài liệu hiện có để xác định vị trí của hướng dẫn kịch bản và các landing page. Xác định lưu đồ quyết định Mermaid xoay quanh các lựa chọn source-of-truth, branching, environment, CI/CD và change-flow được liệt kê. Công việc được xem là hoàn tất khi lưu đồ được nhúng và duy trì, ít nhất ba trang kịch bản bao quát hướng dẫn bắt buộc và mục lục tài liệu liên kết đến các trang đó.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- azure, github-actions
- Lĩnh vực
- cli, devops, documentation
- Loại issue
- Tài liệu
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức độ hoạt động
- Ít trao đổi
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 45/100