計画ワークフローでWikiを使用する
- プラン: Free、Premium、Ultimate
- 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated
GitLab Wikiは、計画ツールと連携します。これは独立したツールではありません。Wikiページをエピック、イシュー、およびボードにリンクできます。GitLabクエリ言語(GLQL)を利用した埋め込みビューを使用すると、Wikiページにイシューと作業アイテムのライブで自動更新されるビューを表示し、ドキュメントを動的なダッシュボードに変えることができます。イシュー、エピック、およびボードとWikiを接続して、ドキュメントと計画が連携するスムーズなワークフローを作成する方法について説明します。
Wikiは、次のものを提供することで、計画ツールを支援します:
- 豊富なドキュメントスペース: イシューの説明に収まらない、複雑な要件、設計上の意思決定、およびプロセスドキュメント。
- バージョン管理されたナレッジ: 仕様と決定に対する変更を長期にわたって追跡します。
- ライブデータビュー: GLQLクエリを埋め込んで、リアルタイムのイシューと作業アイテムデータをWikiページに直接表示します。
- 永続的なコンテキスト: イシューがクローズされた後も、意思決定の背後にある「理由」を保持します。
- 一元的な参照: チームのプロセス、標準、および合意事項に関する信頼できる唯一の情報源。
- 柔軟なフォーマット: 完全なMarkdownサポートによる表、図、および長文コンテンツ。
- 統合されたアクセス制御: WikiはGitLabの既存のロールとアクセス許可システムを使用するため、チームメンバーは、個別の認証なしに、プロジェクトロールに基づいて適切なWikiアクセス制御を自動的に利用できます。
前提要件
このガイドを効果的に使用するには、以下について理解しておく必要があります:
- GitLab Wikiの基本
- GitLab Flavored Markdown
- イシューやエピックなど、さまざまな作業アイテムの作成と管理
Wikiページを作業アイテムに接続する
Wikiドキュメントと計画項目間のリンクを作成して、接続されたナレッジネットワークを構築します。
Wikiドキュメントをエピックにリンクする
エピックでは、エピックの説明が長すぎる詳細な仕様が必要になることがよくあります。完全なドキュメントをWikiに保持します:
左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。
Plan > Wikiを選択します。
詳細な要件を記述したWikiページを作成します(たとえば、スラグ
product-requirementsを使用)。左側のサイドバーで、検索または移動先を選択して、プロジェクトのグループを見つけます。
左側のサイドバーでPlan>エピックを選択し、エピックを見つけます。
エピックの説明で、Wikiページへのリンクを作成します:
## Requirements See full specification: [[product-requirements]] Or with custom text: [[Full PRD|product-requirements]] Or use the full URL: [Full PRD](https://gitlab.example.com/group/project/-/wikis/product-requirements)Wikiページで、エピックへのバックリンクを作成します:
Related epic: &123
想定されるユースケースは次のとおりです:
- 製品要件ドキュメント(PRD)
- 技術設計仕様
- ユーザー調査結果
- 競合分析
- 成功メトリクスとKPI
イシューからWikiを参照する
実装の詳細、標準、およびガイドについて、イシューをWikiページにリンクします:
## Implementation notes
Follow our [[API-design-standards]] when implementing this endpoint.
For local setup, see [[Development Setup Guide|development-environment-setup]].
Definition of Done: [[team-dod]]想定されるユースケースは次のとおりです:
- コーディングの標準とスタイルガイド
- 開発環境のセットアップ
- テストケース手順
- デプロイ手順書
- トラブルシューティングガイド
- オンボーディングドキュメント
Wikiから作業アイテムへのリンク
イシューとエピックをWikiページで直接参照します:
## Current sprint goals
- Implement user authentication: #1234
- Fix performance regression: #1235
- Update API documentation: #1236
## Q3 roadmap
Major initiatives:
- Authentication overhaul: &10
- Performance improvements: &11
- API v2 release: &12クロスプロジェクトWiki参照
他のプロジェクトのWikiページにリンクします:
## Related documentation
See the backend team's API guide: [[backend/api:api-standards]]
Or use the alternative syntax: [wiki_page:backend/api:api-standards]
With custom text: [[Backend API Standards|backend/api:api-standards]]埋め込みビューを使用して動的なダッシュボードを作成する
GitLab Query Language(GLQL)を使用して、Wikiページをライブダッシュボードに変換します。埋め込みビューは、データが変更されると自動的に更新され、Wikiを離れることなく、計画データへのリアルタイム表示レベルを提供します。
埋め込みビューには、パフォーマンスに関する考慮事項があります。大規模なクエリは、タイムアウトになるか、レート制限される場合があります。タイムアウトが発生した場合は、フィルターを追加するか、limitパラメータを減らすことで、クエリのスコープを縮小してください。
基本的な埋め込みビューの構文
GLQLクエリを埋め込むには、言語識別子としてglqlを含むコードを使用します:
```glql
display: table
title: Sprint 18.5 Dashboard
description: Current sprint work items
fields: title, assignee, state, health, labels, milestone, updated
limit: 20
sort: updated desc
query: project = "gitlab-org/gitlab" and milestone = "18.5" and opened = true
```これにより、現在のマイルストーンのすべてのオープンイシューを示すライブテーブルが作成され、イシューが作成、変更、またはクローズされると自動的に更新されます。
計画ダッシュボードの例
Wikiページで直接、包括的な計画ダッシュボードを作成します。
このセクション全体の例では、project = "group/project"を実際のプロジェクトパス(project = "gitlab-org/gitlab"やproject = "my-team/my-project"など)に置き換えてください。
前提要件:
- クエリされたイシューと作業アイテムを表示するためのアクセス許可が必要です。
スプリントの概要ダッシュボード:
```glql
display: table
title: Sprint Overview
description: All work for the current sprint
fields: title, assignee, state, labels("priority::*") as "Priority", health, due
limit: 30
sort: due asc
query: project = "group/project" and milestone = "Current Sprint" and opened = true
```重大なバグトラッカー:
```glql
display: table
title: Critical Bugs
description: High-priority bugs requiring immediate attention
fields: title, assignee, labels, created, updated
limit: 10
query: project = "group/project" and label = "bug" and label = "severity::1" and opened = true
```チームのワークロードビュー:
```glql
display: list
title: Team Work In Progress
description: Active work items by team member
fields: title, assignee, milestone, due
limit: 15
sort: assignee asc
query: project = "group/project" and assignee in (alice, bob, charlie) and label = "workflow::in dev"
```個人のタスクリスト:
```glql
display: orderedList
title: My Tasks
description: Tasks assigned to me, sorted by priority
fields: title, labels("priority::*") as "Priority", due
limit: 10
sort: due asc
query: type = Task and assignee = currentUser() and opened = true
```埋め込みビューは以下をサポートしています:
- 複数の表示形式:
table、list、またはorderedList - カスタムフィールド: 表示するフィールドを選択してください
- ソート: 任意のフィールドで昇順または降順に並べ替えます
- フィルタリング: 複数の条件で複雑なクエリを使用する
- ページネーション: 更に表示を使用して、追加の結果を読み込む
- 動的関数: パーソナライズされたビューには
currentUser()を使用し、日付ベースのクエリにはtoday()を使用します
Wikiによる計画ワークフロー
スプリント計画と実行
スプリント全体で接続されたドキュメントフローを作成します:
スプリント前の計画
- 要件収集: Wikiで詳細な要件をドキュメント化します
- エピックの作成: Wikiの仕様を参照するエピックを作成する
- ストーリーの分解: 関連するWikiドキュメントにイシューをリンクします
- 見積もりメモ: Wikiで見積もりの理由をドキュメント化します
スプリント中
- 毎日のスタンドアップ: ブロックされたイシューへのリンクを含む毎日のWikiページを作成します
- 技術的な決定: 実装イシューへのリンクを含む設計上の決定をドキュメント化する
- 障害: イシュー参照を使用してWikiでブロッカーを追跡します
スプリント後
- レトロスペクティブ: 以下を参照するWikiレトロスペクティブページを作成します:
- 完了したイシュー
- ベロシティメトリクス
- アクションアイテム(新しいイシューとして)
- 学んだ教訓
長期計画ドキュメント
ロードマップに接続する戦略的なドキュメントを維持します:
ロードマップドキュメント構造
roadmap/
├── 2025-strategy
├── q1-okrs
├── q2-okrs
├── architecture-decisions/
│ ├── adr-001-microservices
│ ├── adr-002-authentication
└── technical-debt-registry各ページは、関連するエピックにリンクし、イシュー参照を通じて進捗状況を追跡します。
アーキテクチャの意思決定レコード
トレーサビリティを備えた技術的な意思決定をドキュメント化します。次のようなテンプレートを使用できます:
# ADR-001: Adopt microservices architecture
## Status
Accepted
## Context
[Detailed context...]
## Decision
[Decision details...]
## Consequences
[Impact analysis...]
## Implementation
- Infrastructure epic: &50
- Service extraction: #2001, #2002, #2003
- Monitoring setup: #2004機能横断型チームのコラボレーション
機能横断型チームのコラボレーションハブとしてWikiを使用します:
設計ドキュメント
- 設計仕様を実装イシューにリンクする
- 使用例を含むコンポーネントライブラリを維持する
- エピック参照を使用して設計上の意思決定をドキュメント化する
APIドキュメント
- 実装イシューにリンクするAPIドキュメントを生成します
- マイルストーン参照を使用してバージョニング情報を維持する
- テストイシューにリンクされているサンプルコードを含める
品質保証テスト計画
- エピックの要件にリンクされたテスト戦略
- イシュートレーサビリティを備えたテストケースリポジトリ
- イシューの例を含むバグパターンドキュメント
ナビゲーションと検出パターン
イシューとボードからWikiを見つけやすくする
イシューとエピックのテンプレート
テンプレートにWiki参照を含めます:
## Prerequisites
- [ ] Review [[contribution-guidelines]]
- [ ] Check [[security-checklist]]
- [ ] Read relevant documentation in [[project-wiki-home]]
## Implementation
- [ ] Follow [[coding-standards]]
- [ ] Update [[api-documentation]] if needed
- [ ] Add tests per [[testing-guidelines]]マイルストーンの説明
Wiki計画ドキュメントへのリンク:
## Milestone 18.5
Sprint dates: 2025-02-01 to 2025-02-14
- [[Sprint 18.5 Goals|sprint-18-5-goals]]
- [[Sprint 18.5 Capacity|sprint-18-5-capacity]]
- [[Known Issues|known-issues-and-workarounds]]ボードの説明
Wikiワークフロードキュメントを参照します:
This board follows our [[Kanban Workflow Guide|kanban-workflow-guide]].
For column definitions, see [[Board Column Definitions|board-column-definitions]].Wikiに作業アイテムを表示する
インデックスページを作成する
関連するイシューを収集するWikiページをビルドします:
# Open bugs dashboard
## Critical (P1)
- #1001 - Database connection timeout
- #1002 - Authentication bypass
## High (P2)
- #1003 - Performance degradation
- #1004 - UI rendering issue
## By component
### Authentication
- #1001, #1005, #1009
### API
- #1002, #1006, #1010階層型Wiki構造を使用する
フォルダーと相対リンクを使用してWikiページを整理します:
# Team handbook
## Processes
- [Sprint Planning](processes/sprint-planning) - How we plan sprints
- [Code Review](processes/code-review) - Review standards and SLAs
- [Incident Response](processes/incident-response) - On-call procedures
## Go up to parent page
[Back to Documentation](../documentation)実践的な例
例1: 機能開発ワークフロー
Wikiインテグレーションを使用した完全な機能開発サイクル:
プロダクトマネージャー:
- 市場調査を含む
feature-x-prdWikiページを作成します。 - 次のリンク付きでエピック&100を作成します:
[[Feature X PRD|feature-x-prd]]。 - Wikiに受け入れ基準を追加します。
- 市場調査を含む
エンジニアリングリード:
feature-x-technical-designWikiページを作成します。- 設計ドキュメントをエピック&100にリンクします。
- Wiki参照を使用して、実装イシュー#201〜205を作成します。
エンジニア:
- MRの説明でWiki設計ドキュメントを参照します。
- 意思決定の変更でWikiを更新します。
- イシューをWikiトラブルシューティングガイドにリンクします。
品質保証エンジニア:
feature-x-test-planWikiページを作成します。- テストイシュー#301〜305をテスト計画にリンクします。
- イシュー参照を使用して、Wikiでテスト結果をドキュメント化します。
テクニカルライター:
- Wikiでユーザードキュメントを更新します。
- ドキュメントイシュー#401を作成します。
- Wikiの変更を機能エピックにリンクします。
例2: ライブダッシュボードを備えたチームナレッジベース
リアルタイムのインサイトを得るために、埋め込みビューを使用してチームハンドブックを構成します:
# Engineering team handbook
## Current sprint status
```glql
display: table
title: Sprint Progress
fields: title, assignee, state, labels("workflow::*") as "Status"
limit: 20
query: project = "team/project" and milestone = "Sprint 23" and opened = true
```
## Processes
- [[Sprint Planning Process|sprint-planning-process]] - How we plan sprints
- [[Code Review Guidelines|code-review-guidelines]] - Review standards and SLAs
- [[Incident Response|incident-response]] - On-call procedures
## Technical standards
- [[API Design Standards|API-design-standards]] - REST API conventions
- [[Database Schema Guide|database-schema-guide]] - Schema design rules
- [[Security Checklist|security-checklist]] - Security requirements
## Work management
- [Issue Board](https://gitlab.example.com/group/project/-/boards/123)
- [Current Milestone](https://gitlab.example.com/group/project/-/milestones/45)
- Label taxonomy: [[Label Definitions|label-definitions]]
## Onboarding
- [[New Developer Setup|new-developer-setup]] - Environment setup
- [[First Week Issues|first-week-issues]] - Good first issues: #101, #102, #103
- [[Team Contacts|team-contacts]] - Who to ask for whatクイック参照
Wikiリンク構文
| 目的 | 構文 | 例 |
|---|---|---|
| Wikiページへのリンク(同じプロジェクト) | [[page-slug]] | [[api-standards]] |
| カスタムテキスト付きリンク | [[Display Text|page-slug]] | [[our API guide|api-standards]] |
| クロスプロジェクトWikiリンク | [[group/project:page-slug]] | [[backend/api:rest-guide]] |
| 代替Wiki構文 | [wiki_page:page-slug] | [wiki_page:home] |
| クロスプロジェクトの代替 | [wiki_page:namespace/project:page-slug] | [wiki_page:backend/api:home] |
| 階層リンク(同じレベル) | [Link text](page-slug) | [Related](related-page) |
| 階層リンク(親) | [Link text](../parent-page) | [Up](../main) |
| 階層リンク(子) | [Link text](child-page) | [Details](details) |
| ルートリンク | [Link text](/page-from-root) | [Home](/home) |
| フルURL | 標準Markdown | [API Guide](https://gitlab.example.com/.../wikis/api-standards) |
作業アイテムを参照する
| アイテムの種類 | 構文 | 例 |
|---|---|---|
| イシュー(同じプロジェクト) | #123 | #123 |
| イシュー(異なるプロジェクト) | group/project#123 | gitlab-org/gitlab#123 |
| マージリクエスト | !123 | !123 |
| エピック | &123 | &123 |
| マイルストーン | %"Milestone Name" | %"18.5" |
Wikiからイシューを作成する
イシューに変換できるWikiのタスクリストを使用します:
## Action items from retrospective
- [ ] Improve CI pipeline performance
- [ ] Update documentation
- [ ] Add monitoring for API endpointsチェックボックスを選択し、イシューの作成を使用して、タスクを追跡されたイシューに変換します。
効果的なインテグレーションのためのヒント
ページスラグを正しく使用する
- Wikiリンクはページスラグ(URLフレンドリーバージョン)を使用します:
API Standardsではなくapi-standards。 - ページが存在しない場合、リンクを選択すると作成できます。
- 貼り付けられたWiki URLは、読みやすいテキストに自動的に変換されます(ハイフンはスペースになります)。
双方向リンクを維持する
- Wikiからイシューにリンクする場合は、Wikiページを参照するようにイシューも更新してください。
- 見つけやすくするために、一貫した命名規則を使用してください。
- WebhookまたはCI/CDを使用して、リンクの作成を自動化することを検討してください。
見つけやすいように整理する
- すべての計画ドキュメントのインデックスを作成するWikiホームページを作成します。
- 一貫したページ命名規則を使用します:
sprint-2025-01、adr-001、feature-name。 - 大規模なWikiでは、フォルダーを使用して階層構造を使用します。
- ラベルの分類と一致するカテゴリでWikiページをタグ付けします。
ドキュメントを最新の状態に保つ
- 完了の定義にドキュメントの更新を含めます。
- スプリント計画中にWikiページをレビューします。
- 古くなったページを
archive/フォルダーにアーカイブします。
テンプレートを使用する
一般的なドキュメント用のWikiテンプレートを作成します:
- スプリント計画テンプレート
- レトロスペクティブテンプレート
- 仕様テンプレートの機能
- アーキテクチャ決定レコードテンプレート