Document for Git

GitによるDocumentの管理のすゝめ

従来のドキュメント管理の方法

こんなドキュメント管理してませんか？

従来のドキュメント管理
  • 日付ごとのフォルダで管理
  • 同じ資料を色々な場所に配置

このような管理では…

  • (最新の)資料がどこにあるか探しにくい！
  • 前回との差分が何か分かりにくい！

そこで、Gitによるドキュメント管理はいかがでしょうか。

Gitによるドキュメント管理とは…?

Markdown形式で記載したドキュメントをGitリポジトリで管理すること

Gitとは…?

チーム開発における同時更新を防ぐために、ソースコードなどの変更履歴を記録するバージョン管理システム。

  • 管理対象リソースは、リモートリポジトリと呼ばれる場所に保管される。
  • 編集時、開発(編集)者はリモートリポジトリの複製(ローカルリポジトリ)を作成し、ローカルリポジトリを更新する。
  • 作業完了後、開発(編集)者はローカルリポジトリの内容をリモートリポジトリに反映する。
git

Gitでできること

  • ファイルの変更履歴(更新日、更新者、更新箇所)管理

    • 過去の状態に簡単に戻せる。
    • 差分がわかりやすい。

  • プル(マージ)リクエストによるレビュー

git pr

従来のドキュメント管理の課題解決

  • (最新の)資料がどこにあるか探しにくい！
    → ファイルが一元管理されるので、いつも同じ場所に最新の資料がある！

  • 前回との差分が何か分かりにくい！
    → 変更履歴が残るので更新差分が分かりやすい！ → レビューの仕組みがあるので差分に対しコメントしやすい！

Gitリモートリポジトリ、Gitコマンド、エディタ(VSCodeがおすすめ)があれば作成可能！

リモートリポジトリはMarkdwon形式で書かれたドキュメントをHTMLに変換し描画することができるため、ドキュメントはMarkdown記法で作成する。

markdown

Gitによるドキュメント管理方法 ~レビュー機能(MR,PR)活用~

■ ブランチ戦略例

git branch strategy
ブランチ名 役割
master/main 常にレビュー済みの最新のドキュメントを管理するブランチ。
feature 個別の作業を行うブランチ。コンテンツや章などの単位で作成する。

Gitによるドキュメント管理への疑念

Gitでドキュメント管理できることは分かったけど…

  • 画像の作成や編集はできないんでしょう…？

    • markdownでは、jpgやpng, svgといった画像形式を描画できるけど、 画像自体は別のツールで作ってmarkdownで表示するんでしょ…めんどくさそう。

  • スライドで発表する場合は向いてなくない…？

    • markdownで書いても、発表時にはpowerpointで作成し直すの大変そう

Gitによるドキュメント管理への疑念 ~画像作成・編集~

VSCodeには、Draw.io Integrationという拡張機能が用意されており、VSCodeから直接の画像作成・編集可能です！

また、これにより画像データもバージョン管理可能に！ (パワポだと画像が図として保存されている場合があったりする…)

drawio

Gitによるドキュメント管理への疑念 ~スライド作成~

VSCodeには、Marp for VS Codeという拡張機能が用意されており、Markdownで記載されたドキュメントをスライド(pdf)に変換です！

height:295

ただし、Powerpointのように画像や文字を直観的に配置できないなど課題もあります。 →スライドを作成することが目的な場合やリッチなスライドの作成には向いていなそう。

最後に

Gitによるドキュメント管理

  • Markdownで作成したDocumentをGitリポジトリで管理する。
メリット デメリット
・いつも同じ場所に最新の資料がある
・レビューがしやすい		 ・パワポやその他形式への変換はまだまだ難しい

私が考えるGitドキュメント管理の使いどころ

すべてのドキュメントをGit管理するのではなく、まずは テンプレート指定のない内部向け文書(運用手順書、システム構成) からGitでのドキュメント管理を初めてみてはいかがでしょうか。