Azure / Azure/apiops-cli

Add scenario-based documentation with decision flowchart

オープン
#134 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る
Enhancement P2
主要言語
TypeScript
スター
26
フォーク
9
平均マージ
1日 3時間
マージ済み PR(30日)
20

説明

## 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

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

Start by reviewing the existing documentation structure and navigation to identify where the scenario guide and landing pages belong. Define the Mermaid decision flowchart around the listed source-of-truth, branching, environment, CI/CD, and change-flow choices. Done means the flowchart is embedded and maintained, at least three scenario pages cover the required guidance, and the documentation index links to them.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
azure, github-actions
領域
cli, devops, documentation
issue の種類
ドキュメント
難易度
5/5
見積もり時間
1週間以上
活発さ
静か
明瞭さ
おおむね明確
初心者へのやさしさ
45/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。