GitHub のアラート記法でもっとコミュニケーションを活性化させていきたい

昨年末に追加された GitHub のアラート記法についてご存知でしょうか？ アラート記法は、重要な情報を強調する際に使用することを目的としたマークダウン拡張の記法です。

Gaji-Laboでは、スタートアップ支援の中でコミュニケーションを大切にしたチーム開発を行っています。

せっかく追加された機能ですから、ぜひ活用してコミュニケーションを活性化させていきたいのですが、うまい使いどころが見つからず早半年……。

今回は、このアラート記法を上手に活用する方法を考えてみたいと思います。

使い方

GitHub で利用できるアラート記法には以下の5種類があります。それぞれ目的に応じた情報を強調するために、以下のように使用します。

> [!NOTE]
> これはノートです。ユーザーが内容をざっと見たときでも把握しておくべき情報を強調します。

> [!TIP]
> これはヒントです。作業をより簡単にするためのアドバイスを提供します。

> [!IMPORTANT]
> これは重要な情報です。ユーザーが目標を達成するために知っておくべき重要な内容です。

> [!WARNING]
> これは警告です。問題を回避するためにユーザーが直ちに注意を払うべき情報です。

> [!CAUTION]
> これは注意です。特定の行動によって生じる可能性のあるリスクや負の結果について警告します。

ドキュメント上では以下のように強調表示されます。

注意点

見た目も綺麗で目立つカラーリングなので様々な場面で使ってみたくなるのですが、公式のドキュメントには以下のように使用上の注意が明記されています。

アラートは、ユーザーの成功に不可欠な場合にのみ使用し、読者へ過剰な負荷をかけないよう、記事ごとに 1 つまたは 2 つに制限してください。 さらに、アラートを連続して配置しないようにする必要があります。

基本的な書き方とフォーマットの構文

つまり、綺麗で目立つからこそ”ここぞ”という場面で使用することが推奨されているわけです。

では、その”ここぞ”という場面はいつなのでしょうか？

使いどころ

使いどころとしては、主に README.md や Wiki などのドキュメントの作成時、Issue や PR を立てる時に使用するのがおすすめです。

読む人間が見逃してはいけない重要な情報を強調するために装飾したり、手順書やガイドラインで特に注意が必要な部分を明示するために使用します。

コメントでも使用することはできますが、複数のコメントが連なる状況で使用すると視覚的に煩雑になってしまう印象です。

プロジェクトのルールにもよりますが、コメントで多用するのには注意が必要かなと思いました。

さいごに

GitHubのアラート記法は、カラフルな見た目で手軽に強調できる一方、使いすぎると逆に本当に重要な部分がどこなのか分からなくなってしまいます。

その効果を活かすには、前述の注意点を加味しつつ、チーム内で使用ルールを決めて共通認識を持った上での利用するのが良さそうだなと感じました。

もし、使用するタイミングの擦り合わせなく使いたい場合は、使い方により一層気をつける必要があります。

活用する際は「less is more（少ない方が豊かである）」の原則を心に留め、本当に重要な情報のみを強調するよう心がけたいですね。

Gaji-Labo ではコミュニケーションを大切にしたチーム開発を行っています。
興味のある方は、ぜひ採用情報をチェックしてみてください！