Markdown + Gitでナレッジ管理をオススメする理由

こんにちは!たぬきうどんです!

私は2018年に非IT業界から未経験でエンジニアに転職し、現在までエンジニアとして働いています。

この記事はMarkdown + Gitでナレッジ管理をオススメする理由について書いています。

ナレッジ管理で迷っている方はぜひ御覧ください。

はじめに

皆さんはプログラミング学習等で得た知識や経験、また、会社のルールといった、いわゆる「ナレッジ」の管理はどう行っていますか?

ナレッジ管理には十人十色、様々な管理方法があります。

ただ、現状のナレッジ管理に不満を持っている人も少なくないでしょう。

そういうときに私がオススメするのはMarkdownとGitを使ったナレッジ管理

Markdownの書き方とGitを使うことができれば、簡単にナレッジ管理ができます!

この記事では

ナレッジ管理したいけど、いい方法ないかなぁ

だったり、

社内Wiki作りたいけど、どうしよう…

と考えている方々の参考になる記事ですので、ぜひ御覧ください!

Markdown + Gitでナレッジ管理をオススメする理由

私がMarkdown + Gitでナレッジ管理をオススメする理由は以下です。

  • Markdownのルールに従って書くことで、わかりやすい構成にできる
  • 軽量なプレーンテキスト(Markdownファイル)でナレッジを貯めることができる
  • 更新履歴がわかりやすい
  • GitHubのようなソースコードホスティングサービスを利用することで、簡単にナレッジベースを構築できる

それぞれの項目について説明します。

Markdownのルールに従って書くことで、わかりやすい構成にできる

Markdown(マークダウン)

文書の構造や修飾情報を記述するマークアップ言語の一つ。

Markdown(MD)とは -IT用語辞典 e-Words

で、Markdown記法をもとに文書の構造や修飾情報を記述していきます。

このMarkdown記法には以下の様なものがあります。

Markdown
# 見出し1
## 見出し2
### 見出し3

**太字**

*斜体*

> 引用

[リンク](http://example.com)

上記のMarkdwonをプレビューできるVS Codeのようなエディタで見ると、以下のように表示されます。

VS Codeでプレビュー

このようにMarkdown記法に従い、ナレッジを記述していくことで、見出しや引用文等の記述方法を統一することができ、わかりやすい文章構成にすることができます

軽量なプレーンテキスト(Markdownファイル)でナレッジを貯めることができる

Markdownは本来、

書きやすくて読みやすいプレーンテキストとして記述した文書を、妥当なXHTML(もしくはHTML)文書へと変換できるフォーマット

Markdown – Wikipedia

といったものなので、テキストファイルのようなプレーンテキストにMarkdown記法で書いていくことになります。

Markdwonで記述されたテキストファイル(Markdownファイル)は余計な情報を含まないので、基本的には軽量です。

このようにファイルサイズを余計に大きくすることなくナレッジを貯めることができ、テキストエディタでもサクサク動作させることが可能となります。

更新履歴がわかりやすい

Markdown + Gitでナレッジ管理をおすすめする理由3つ目は更新履歴がわかりやすいことです。

MarkdownファイルはMicrosoft Wordといったようなバイナリファイルではなく、テキストファイルが基本です。

そのため、Gitで差分を確認する場合は人間に読める内容になります。

このように、Markdownファイルでナレッジを貯め、そのナレッジをGitで管理することで、差分で効率よく更新履歴を確認することが可能になります

差分の他にも、コミットメッセージに修正内容を入れるといった運用を行うことで、コミットメッセージだけでそのような修正が入ったかが分かるようになります。

GitHubのようなソースコードホスティングサービスを利用することで、簡単にナレッジベースを構築できる

Markdown + Gitでナレッジ管理をおすすめする最後の理由はGitHubやGitLab、Bitbucketといったソースコードホスティングサービスを利用することで、簡単にナレッジベースを構築できることです。

上記サービスを使用すれば、Markdownファイルのプレビューもブラウザ上で確認することができます。

GitHubでのプレビュー例

また、チームでこのようなサービスを利用している場合、情報共有も簡単になります。

運用する上での注意

運用する上で大事なことはルールを決めることです。

決まったツールを使わない限り、Markdown + Gitでナレッジ管理する場合は決まったフォーマットがなく、自由に運用することが可能です。

個人で運用する場合もチームで運用する場合も、自由すぎると逆に運用に困ることがあります。

そのため、

  • 階層は何階層までにするのか
  • 画像等のアセットを置く場所をどうするのか
  • 見出し(#, ##)はどのように使用するのか

といったような最低限のルールは制定しておくことをオススメします。

制定したルールはプロジェクトのルートにREADEM.mdファイルを作成し、その中に記述しておくのが良いでしょう。

終わりに…

以上がMarkdown + Gitでナレッジ管理をオススメする理由でした。

ナレッジ管理ツールやサービスが溢れている昨今、Markdwon + Gitでのナレッジ管理方法はシンプルな方法となっています。

ただ、チームのナレッジを管理する場合、チームの状況によってはMarkdownやGitの学習コストがかかるので、その点はご注意ください。

この記事が皆さんの助けになれば幸いです!

最後まで読んでいただき、ありがとうございました!

コメントを残す

メールアドレスが公開されることはありません。