wikiにどのような情報をどのように残すか？

方法論
環境構築
Author

Ryo Nakagami

Published

2025-05-23

Key Takeaways
  • Wiki は，みんなが自由に編集できる Web サイト
  • 書かないよりかは書く！
  • 慣れてきたら，ストック情報を意識して何をWikiに記載すべきか判断する
  • メタデータ（タイトル，作成者，更新日，タグ，関連資料など）を活用することで，情報の検索性・管理性・再利用性が向上する

1. Projectと情報共有の課題

仕事の中で情報共有の課題はしばしば発生します．その発生の仕方は以下の２つが代表例としてあります．

課題1：必要な情報が共有されていない

事象 問題分類
退職・異動時に「前任者しか知らないこと」が多く，後任が混乱 属人化問題
同じ業務でも人によってやり方がバラバラ（手順の標準化がされていない） ナレッジの一元化できてない問題
毎回「この件ってどうやるんでしたっけ？」という質問が発生する 非効率なコミュニケーション

課題2：必要な情報を見つけるのが難しい

事象 問題分類
手順書は共有フォルダ，仕様はメール，背景はSlack…とバラバラ 情報の散逸問題
検索しても古いバージョンや関係ない資料が出てきて混乱 情報の最新化・正確性問題

2. ProjectにおけるWiki

Definition 1 Wiki

プロジェクトやチームの知識・ノウハウ・手順・ルールなどを，誰でも編集・追加できる形で蓄積・共有するためのドキュメントシステムのことをWikiと呼ぶ．

Wikiは，単なるメモやドキュメントの集積ではなく，以下のような効果を持ったプロジェクトの「知識のインフラ」として機能します．

  • ナレッジの一元化
  • 属人化の防止
  • コミュニケーションの効率化

ナレッジの一元化

ナレッジの一元化とは，プロジェクトやチームに関する情報・ノウハウ・手順・ルールなどを，分散せずに一箇所（Wikiなど）に集約して管理することを指します．これにより，以下のようなメリットがあります。

  • 情報の散逸防止
    • 口頭や個人メモ，チャットログなどに分散しがちな情報を，Wikiにまとめることで「どこに何が書いてあるか分からない」「必要な情報が見つからない」といった事態を防げます
  • 情報の最新化・正確性の維持
    • 仕様変更や新しい知見が得られた際，Wikiを更新するだけで全員が最新情報を参照でき，古い情報によるミスや認識ズレを防止できます

属人化の防止

属人化とは，特定の業務やノウハウが一部の人だけに依存し，その人がいないと作業が進まない・問題が解決できない状態を指します．Wikiは以下の観点からこの属人化を防ぐための有効なツールです．

  • 情報の共有・可視化
    • 業務手順やトラブル対応，設定方法などをWikiに記録することで，誰でも同じ情報にアクセスできるようになります
    • これにより，担当者が不在でも他のメンバーが対応可能となり，業務の停滞を防げます
  • ノウハウの蓄積と継承
    • 経験者が持つ暗黙知やコツを明文化してWikiに残すことで，後任者や新メンバーへのスムーズな引き継ぎが可能になります
  • チーム全体のスキル底上げ
    • 皆がWikiを活用・更新することで，チーム全体の知識レベルが向上し，特定の人に依存しない強い組織づくりにつながります

コミュニケーションの効率化

コミュニケーションの非効率とは，情報が構造化されていないことや，一元管理されていないによって発生する無駄な時間のことです．例として以下のようなものがあります

課題・現象 コスト分類
毎回同じ質問が繰り返される 説明コスト
情報が人によってバラバラで食い違う 認識齟齬コスト
確認・共有・引き継ぎに時間がかかる 説明コスト・情報探索コスト
メールやチャットを遡らないと情報が見つからない 情報探索コスト

Wikiを活用することで上記のような「説明コスト」「認識齟齬コスト」「情報探索コスト」を以下のような機序で削減することができます

  • 説明コストの削減
    • よくある質問や手順，ルールなどをWikiにまとめておくことで，同じ内容を何度も口頭やチャットで説明する必要がなくなります
    • 新メンバーや他部署からの問い合わせにも「Wikiを参照してください」と非同期コミュニケーションの案内でき，対応コストを大幅に削減できます
    • 仕様や方針，過去の議論の経緯などをWikiに記録しておくことで，議論のたびに一から説明したり，過去の経緯を探す手間が省けます
  • 認識齟齬コストの低減
    • Wikiに記載された内容は誰でも同じものを参照できるため，伝言ゲームによる情報のズレや誤解を防げます
  • 情報探索コストの低減
    • 業務に必要な情報（手順・FAQ・ルール・用語解説など）を構造的に蓄積・整理することで，情報の「どこにあるか」「最新版はどれか」を探す時間を減らすことができます

3. Wikiに書くべき情報

Wikiには情報を多く残せば残すほど基本的に良いですが，「フロー」と「ストック」という観点で情報を事前に整理することがより良いwikiへと繋がります．Wikiはストック型の情報を蓄積する場所であるので，「これはストック化すべき情報だ」と事前に分類・判断して整理する必要があります．

フロー情報

  • 時系列に流れていく情報
  • 生まれた直後は価値が高く，時間やプロジェクト進行の経過と共に価値が下がっていく
  • 例: Slackやメールでのやり取り，日報・会議メモなど

ストック情報

  • 長期的に価値があり，何度も参照される情報
  • 例: マニュアルや設計書，仕様書など

「フローとストックの区別」と良いWiki

「フローとストックの区別」の視点を持つことで，以下のようなメリットがあります：

  • Wikiがごみ箱化せず，構造的に整理される
  • 情報の探しやすさが向上

具体的な運用例

情報の種類 最初は その後
新しいやり方の試行錯誤 Slackで議論（フロー） 成功したら手順をWikiに整理（ストック）
問い合わせへの回答 チャットで返す（フロー） よくある質問ならFAQとしてまとめる（ストック）
プロジェクトの背景や目的 議事録で共有（フロー） 重要事項はWikiのプロジェクトページに追記（ストック）

4. Coding ProjectでWikiに書くべき情報

Goal: 開発メンバー全員が迷わず効率よく開発・運用できる

  • Wikiを書く目的は情報伝達の課題を解決するため
  • Coding Projectにおいて情報伝達課題の解決はプロジェクトの生産性・品質・持続性を大きく左右する
Wikiに書く内容 どの「迷い」や「非効率」を減らすか
環境構築手順 「動かない」「セットアップ方法がわからない」
技術スタック・設計方針 「なぜこの技術を使ってるの？」「全体像が見えない」
コーディングルール・ブランチ戦略 「このファイル名でいい？」「この書き方でOK？」
デプロイ手順・運用ルール 「本番反映って誰がどうやってるの？」
FAQ・トラブル対応 「よくあるエラーが出た，どうすればいい？」

5. metadata fieldの活用

metadata fieldを明確に設定することで，情報の管理性・検索性・再利用性が大きく向上します．

metadata field活用の効果

目的 メタデータが果たす役割
検索性向上 タグ・対象環境・チームでフィルタリング可能
責任の明確化 作成者/責任者がわかることで内容の信用度が上がる
鮮度の判断 更新日で「使える情報か？」を判断できる
ナレッジの繋がり 関連リンクでページ間の文脈を可視化できる

metadata field項目例

フィールド名 内容 記入例・補足
タイトル / name ページの内容をひと目で表すタイトル 環境構築手順（ローカル） / バックエンド設計方針
作成者 / author 初期作成者，または責任者 r.nak（Slack名やGitHubアカウントで統一）
最終更新日 / last_updated 内容が最後に更新された日時 2025-05-23（日付のみ or タイムスタンプ）
関連タグ / tags 分類や検索性向上のためのタグ群 #backend, #setup, #api, #infra
対象環境 / environment 適用される環境やバージョン範囲 local, staging, v2.3.1〜
関連資料 / related_docs 他ページや外部リンクへの参照 [デプロイ手順](../deployment.md) / URL可
更新履歴 / changelog 主な更新内容と日付 2025-05-23: Docker対応を追加
2025-03-01: 初版作成

metadata field実装例

---
title: "ローカル環境構築ガイド"
author: "r.nak"
last_updated: "2025-05-23"
tags: ["setup", "backend", "docker"]
environment: "local"
team: "backend"
is_obsolete: false
related_docs:
  - "../deployment.md"
  - "https://example.com/db-guide"
changelog:
  - "2025-05-23: Docker対応を追加"
  - "2025-03-01: 初版作成"
---
  1. ページの冒頭に「テーブル形式」でメタ情報を記述
  2. テーブルを「ページプロパティマクロ」で囲む
  3. 他ページから「ページプロパティレポートマクロ」で一覧化が可能

5. Wiki運用Tips

Wikiは「作って終わり」ではなく，「育てて使い続ける」ことで真価を発揮します．一方，更新を怠り最新情報が反映されていなかったり，信頼性が低い内容が記載されていたりなど実運用ではトラブルが発生します．

トラブル1：情報が乱立・重複してどれが正しいか分からない

原因・目的 対策内容 効果・備考
情報の分類が曖昧・乱立しやすい タグを事前定義（例：setup, troubleshooting, design, infra, FAQ） ページの役割や内容を明確化し，重複や検索漏れを防ぐ
ページの乱立・重複・古い情報の放置 定期的な「重複・類似ページ見直し会」（ミニレビュー） 定期的な棚卸しで情報の鮮度・整理を維持し，正しい情報を残す
古い情報や非推奨手順が残りやすい is_obsolete: true フラグで非推奨情報を明示 利用者が「どれが最新・有効か」を一目で判断できるようにする

トラブル2：情報の更新漏れで古い手順が誤用される

原因・目的 対策内容 効果・備考
情報の鮮度が分からず古い手順が誤用される 「更新日」フィールドを必須化 ページごとに最新更新日が明示され，利用者が情報の新旧を判断しやすくなる
実運用の変更がWikiに反映されないまま放置される PRや障害対応のチェックリストに「Wiki更新」を追加 運用変更や障害対応のたびにWiki更新を強制し，情報の陳腐化・誤用を防ぐ

トラブル3：誰が書いたのか分からず，内容の信頼性が低い

原因・目的 対策内容 効果・備考
ページの責任者が不明で内容の信頼性や更新責任が曖昧になる すべてのページに「Author（責任者）」を必須項目として設定 責任者が明確になり，内容の信頼性・更新体制が向上する
担当者不在で情報が放置される 作成者が異動・退職したページの担当を再割当 継続的な管理・更新体制を維持できる
責任者不明ページの放置・情報の陳腐化 「責任者が不明なページ一覧」を抽出し，棚卸しリストに追加 定期的な棚卸しで責任者を再割当し，情報の鮮度と信頼性を保つ

トラブル4：一部の人しかWikiを更新しない

原因・目的 対策内容 効果・備考
書き方が分からず記載が進まない・属人化 テンプレートを整備し，書く敷居を下げる 誰でも迷わず記載でき，情報の質と量が安定する
重要な情報が口頭やチャットで流れてしまう SlackやMTGで「この話Wikiに書いておこう」と声かけする文化作り 情報のストック化が進み，ナレッジの蓄積・共有が促進される

トラブル5：作っても使われない

原因・目的 対策内容 効果・備考
重要情報が分散し見つけづらい オンボーディング資料，障害手順書，開発ルールなど，必ず参照する情報をWikiに集約 必要な情報が一箇所で見つかり，迷いなく参照できる
質問・回答がチャットで流れてしまう Slackで「この質問，Wikiにありましたよ」文化をつくる 情報のストック化が進み，同じ質問の繰り返しを防ぐ
Wikiの構造が複雑・不親切 初心者でもどこから見ればいいか分かる構造をつくる 迷わず必要な情報にたどり着ける，オンボーディングも円滑
利用者視点の改善が進まない ユーザーを巻き込むUI改善アンケートやフィードバック導線 実際の利用者の声を反映し，使いやすいWiki運用が実現できる

References