脱Excelで設計書を作成する(Gitlab Wiki整備編)

今回やること

設計書の脱Excel計画、いよいよ作業に取り掛かります。
まずはWikiページ構成の検討とページの作成を行います。

※脱ExcelでMarkdownに至った経緯はこちらをご参照ください。

Wikiページ構成の検討

ページ構成の検討が必要な理由として

• 複数人が編集してもバラツキが生じないようにする
• Wiki利用者が利用しやすいドキュメントを目指す（ユーザビリティの高いドキュメント）

が挙げられます。
ユーザビリティが高いWikiを目指すために意識する内容は

• 知りたい情報の場所が特定しやすい(効率)
• 読み手と書き手で情報の齟齬が生じない(有効性)
• 読み手側に不快感が生じない(満足度)

が満たされているとユーザビリティが高いと言えそうです。
ページ構成はこの中の効率と満足度の部分に影響します。

考えうるページ構成案をいくつか提示します。

設計ごとに分ける

メリット：ドキュメントの種類ごとに分かれているので資料のスコープを意識する必要がない

例えば「このAPIは機能Aと機能Bで使うけど、機能Aと機能Bのどっちに書けばいいのだろう」といったことは起きない。

概要設計
　├インセプションデッキ
　├プロダクトバックログ
　...
画面設計
　├画面一覧
　├画面遷移図
　├ページ共通部分仕様
DB設計
　├DB一覧
　├テーブル定義
　...
API設計
　├API一覧
　├API仕様

以下略

機能ごとに分ける

メリット：特定の機能について知りたい人が情報を閲覧しやすい。

プロジェクト関係
　├インセプションデッキ
　├プロダクトバックログ
　...
機能A
　├画面一覧
　├画面遷移図
　├DB一覧
　├API一覧
　...
機能B
　├画面一覧
　├画面遷移図
　├DB一覧
　├API一覧

以下略

今回は設計ごとに分ける方式を採用しました。どちらを採用するかで優劣はそんなにないと思っています。

ページ作成

ページ構成が完成したらいよいよページの作成に移ります。
各設計書は次回の記事で作成しますので、今回はWikiを構成するためのページを作成します。
トップページ→サイドバー→Wiki利用方法ページ→各設計書の順で作っていきます。

トップページ

なぜ最初にトップページなのか

これは単純で、Wikiのトップページが作られていないと毎回新規作成ページに飛んでしまうのが気になるからです。
※左のWikiを押すたびに画像のようになります。

もう一つ理由を挙げるとするならば、トップページにプロジェクトの概要や資料の場所などを載せておくことでまだWikiが未完成の状態でも、開発者に「トップページ見てプロジェクトの概要とか把握しておいて！」と伝えられます。

作成例

内容については各プロジェクトで好きなように決めていいページになりますので、あくまで一例としてご紹介します。

## プロジェクト方針
本PJについて以下の方針をもとに実施するものとします。
1. チームとして開発するためにアジャイル開発手法を採用し、Webシステムの開発をするプロセスや機能を実装するために必要なことを理解する。
1. 全員が各ロール(フロントエンド、バックエンド、アーキテクトなど)を体験し、役割や実施すべきことを把握できるように取り組んでいく。（各メンバーのロールを固定しない）

以下略

## 目的
弊社の現状の開発手法は最近の時代の流れの速さについていけていない部分があり、アジャイルでの開発も
手の内に加えておく必要があると感じた。

以下略

## 期間
2022年10月～2023年1月までの4ヶ月

## 取り組む内容
本PJを遂行するにあたり、以下の内容を実行します。
- 模擬案件を用意し、既存システムを参考にしたWebシステムを構築します。
- プロダクトオーナー、スクラムマスター、開発チームをそれぞれ用意し、スクラムで開発を実施します。

以下略

## 資料
本PJに関連するパス一覧はこちらです。
||パス/URL|
|---|---|
|ファイルサーバ|（ここにファイルサーバのパス）|
|設計書|当Wiki|
|課題管理|（ここにバックログのURL）|
|サイトURL|（ここに構築したWebサイトのURL）|

以下略

サイドバー

各ページより先にサイドバーを作る理由

サイドバーを先に作ることで

• どのページを作ればいいのかを改めてまとめる機会になる
• サイドバーで順番を定義して見やすくする
• Gitlab Wikiの仕組みで、ページが作成されていないリンクを踏むと新規作成ページに飛ぶので楽

といったメリットがあります。

Edit sidebarというリンクがサイドバーの上にあるので、そこから編集します。

作成例

まず先頭にホームページのリンクを載せます。
Gitlabの場合[]の中にリンク表示名、()の中にリンク内のパスを書くことでリンクが作成できます。
また、リンク内のパスはスラッシュ始まりで書き始めます。
例：/画面設計書/テーブル定義/hogehogeテーブル

各ページへのリンクをネストしながら箇条書きリストで書くことで階層がわかりやすくなります。
後ろのほうにWiki利用方法ページとすべてのページの一覧が乗っているページへのリンクを作成します。

サイドバーですが、表示制限があるので長くなりすぎると途中で見切れます。
そのためページ数が多い場合は「〇〇一覧」のような画面を作成して、その中でさらに各ページのリンクを貼るようにするとサイドバーに載せるページ数を抑えられます。

/pagesはWikiにデフォルトで用意されるページです。作成したページの一覧を見ることができます。
ページを作成すると自動で追加されるのでメンテナンス不要です。

[ホーム](/home)
* Azure
  * [構成図](/全体/Azure/構成図)
  * [ポリシー](/全体/Azure/ポリシー)
  * 監視設定
    * [コストアラート](/全体/Azure/監視設定/コストアラート)
    * モニター
      * [CPU/メモリ](/全体/Azure/監視設定/モニター/CPU/メモリ)
      * [リソース死活監視](/全体/Azure/監視設定/モニター/リソース死活監視)
      * [サイト死活監視](/全体/Azure/監視設定/モニター/サイト死活監視)
  * [リソースグループ](/全体/Azure/リソースグループ)
  * リソース設定
    * [Virtual Network](/全体/Azure/リソース設定/Virtual Network)
    * [Subnet](/全体/Azure/リソース設定/Subnet)
    * [Network Interface](/全体/Azure/リソース設定/Network Interface)
* 概要設計書
  * [要件定義](/概要設計書/要件定義)
  * [機能要件](/概要設計書/機能要件)
  * [非機能要件](/概要設計書/非機能要件)
* DB設計書
  * [DB一覧](/DB設計書/DB一覧) 
* 画面設計書
  * [ページ全体仕様](/画面設計書/ページ全体仕様)
  * [画面一覧](/画面設計書/画面一覧)
  * [画面遷移図](/画面設計書/画面遷移図)
* API設計書
  * [API一覧](/API設計書/API一覧)

[Wikiについて](/Wikiについて)  
[View All Pages](/pages)

2023/08/02追加 サイドバーに折り畳みを追加する方法

<details>
<summary>セキュリティ診断</summary>

* [ポート診断](/セキュリティ診断/ポート診断)

</details>

折り畳み状態

展開

Wiki利用方法ページ

これはある程度習熟度が高いメンバーなら不要かもしれませんが、今回Wikiを使うのが初めてなメンバーが多いのでWikiツリーの説明をまとめたページを用意しました。

作成例

# Wikiについて
ホーム📝：プロジェクト全体の説明、資料のパス一覧等を記載します

Azure📁  
　├リソースグループ📝：リソースグループの仕様を記述します  
  ├構成図📝：Azure構成図を記述します  
　├リソース設定📁  
　　　├Network Interface📝：Network Interfaceの仕様を記述します  
　　　├Virtual Machine📝：Virtual Machineの仕様を記述します  
　　　...  
概要設計書📁   
　├要件定義📝：要件定義を記述します  
　├機能要件📝：機能要件を記述します  
　├非機能要件📝：非機能要件を記述します  
DB設計書📁  
　├DB一覧📝：DBの一覧を記述します  
　├ER図📁  
　│　├ER図①📝：ER図①の仕様を記述します  
　│　├ER図②📝：ER図②の仕様を記述します  
　│　...  
　├DB名📁  
　　　├DB情報📝：DBの定義やテーブル一覧を記述します  
　　　├権限設定一覧📝：DB/テーブル/シノニムに対する権限の一覧を記述します  
　　　├テーブル定義📁  
　　　　　　　├テーブル①📝：テーブル①の定義を記述します  
　　　　　　　├テーブル②📝：テーブル②の定義を記述します  
　　　　　　　...  
画面設計書📁  
　├ページ全体仕様📝：ヘッダ/フッダ、エラーページなどページ全体の仕様を記述します  
　├画面一覧📝：画面の一覧を記述します  
　├画面遷移図📝：画面遷移図を記述します  
　├画面仕様📁  
　　　├画面①📝：画面①の仕様を記述します  
　　　├画面②📝：画面②の仕様を記述します  
　　　...  
API設計書📁  
　├API一覧📝：APIの一覧を記述します  
　├API仕様📁  
　　　├API①📝：API①の仕様を記述します  
　　　├API②📝：API②の仕様を記述します  
　　　...  


## 設計書作成のコツ
* Wikiの別のページへのリンクを貼ることでより一層情報を追いやすくなります。（特に〇〇一覧系のページ）
* なるべく文章で表現することで、後々更新した際の差分がわかりやすくなります。（画像だと差分がわかりづらくなります）

## Wiki作成時参考ドキュメント
[こちら](https://gitlab-docs.creationline.com/ee/user/project/wiki/)

Gitlabでは文末に半角スペースを2個付けると改行という仕組みですのでご注意ください。

次回

次はマークダウンで設計書を作成する段階に入ります。

参考サイト

ページ構成についてサイボウズ様公開の研修資料を参考にいたしました。