「もっとイケてる感じでハンズオン資料を作りたいけどなんかいい方法ないかなあ」と思っていたところ、以前に「GoogleのCodelabsがいいらしい」と聞いたことがあったのを思い出したので方法を調べてみました。
するとこちらの記事でとても丁寧に紹介してくださっていたんですが、
自分の環境だと書かれている手順でうまくいかなかったので他にも色々調べながら行ったやり方や感想を記載します。
僕の場合、途中で詰まったので1時間半くらいかかった気がしますが、スムーズにいけば30分もあれば動作確認できるんじゃないでしょうか。
Codelabsとは？
CodelabsはGoogleがチュートリアル形式で公開をしている学習コンテンツです。具体的なコンテンツとしてはAndroidやGCP、TensorFlow、Firebase、Flutterなどがあるみたいです。
公開されている資料の一覧はこちらのページから見れます。
サンプルとしてこちらの資料を見てもらうと、順を追って分かりやすくチュートリアルを進めていけるのが分かるんじゃないかと思います。
今は全体のステップの中のどこをしているのかというのを常に意識できるのが学習効果をアップしてくれそうです。
また、こんな感じの資料をインターネット経由で閲覧できると資料の配布やDLの手間もかからないので楽ちんですね。
「CLaaT」を使うとCodelabs形式の資料を自分で簡単に作成できる
最初に調べてた時は「CLaaT」と「Codelabs」の関係がごっちゃになってたんですが、CLaaTを使うとCodelabsと同じ形式の資料を自分で作れます。言わば「CLaat=Codelabs作成ツール」ですね。
CLaaTのGitHubページはこちらになります。
ちなみに他の記事を見ると「claat」と書いている記事がほとんどでしたが、GitHubには「CLaaT」 (Codelabs as a Thing) と説明があったのでこちらが正式名称なんですかね。（一応この記事では「CLaaT」で書いてます。）
GitHubで紹介されているCLaaTを使う利点は抜粋すると以下の通り。
- Googleドキュメントで簡単に作成
- Markdownテキストでの作成もサポート
- コードを記述することなくインタラクティブなチュートリアルを作成可能
- 匿名、アカウント不要で利用可能
- 中断して戻ってきたときに続きから再開できる
- レスポンシブで美しいデザイン
- モバイルフレンドリーなユーザーエクスペリエンス
余談にはなりますが「Codelabs as a Thing」という名前がなんともGoogleっぽい？感じがします。直訳すると「モノとしてのコードラボ」ですが、「（あなたの）モノとしてのコードラボ」「（自由に使える）モノとしてのコードラボ」ってことなのかなあとか思いましたがどうなんでしょう。
環境構築（Windows）
方法としてはこちらのページにあるインストーラーを使う方法とGo言語の【Go get】コマンドを使う方法があるようです。
僕は最初インストーラーでやったんですが、インストールしてもコマンドが使えなかったのでGoを使ってセットアップしたらあっという間に終わりました。
手順としては3ステップです。
1. Goのインストール
こちらからGoの実行に必要な環境をインストールします。
2. 環境変数の設定
Windowsの方はGoの環境変数にインストールしたフォルダを指定しましょう。
コントロールパネル > システムの詳細設定 > 環境変数 と遷移します。
続いて [ユーザーの環境変数] 欄から Path を選択して [編集] ボタンをクリックしてインストールしたGoの実行環境フォルダを指定しましょう。
設定後は go version とコマンドプロンプトから入力して、バージョンが表示されればOKです。
3. CLaaTをインストール
以下のコマンドを実行してCLaaTをインストールします。
$ go get github.com/googlecodelabs/tools/claat
コマンドプロンプトから claat help コマンドが使えることを確認できればインストールは完了です。
資料作成 ～Googleドキュメントで作る場合～
特徴
Googleドキュメントで簡単に編集できて、Chromeの拡張機能を使えば最終的な完成イメージもその都度確認できるのでサクッと資料を作れます。
作り方の概要
こちらはこの記事の冒頭で紹介した「claatツールを使って簡単にGoogleドキュメントでハンズオン手順を作る - Zenn」
を書かれている たけださん がGoogleドキュメントに手順を分かりやすくまとめてくれていますのでこちらをご覧ください。
ファイルを編集して使いたい場合は、編集リクエストではなく「ファイル＞コピーを作成」でドキュメントをコピーして使ってくださいとのことなのでご注意ください。
Chromeの拡張機能でプレビュー
Chromeの拡張機能の「Preview Codelab」を使うと作成途中のGoogleドキュメントをCodelabs形式でプレビューしながら資料を作成できます。
Previw CodelabをインストールしたらChromeの右上にPreview Codelabのアイコンが追加されます。
Googleドキュメントを開いた状態でアイコンをクリックすると別タブでプレビューを確認できます。
作成した資料をエクスポート
GoogleドキュメントのURLは以下の形式で作られています。
https://docs.google.com/document/d/xxxxxxxxxxxx/edit#
このxxxxxxxxxxxの部分をメモしておき、資料を出力したいフォルダで以下のコマンドを実行するとエクスポートできます。
$ claat export xxxxxxxxxxxxxxxxxxxxxxxxx
ok codelabs-tool
但し、初回の実行時には以下のように認証を求められます。
Authorize me at following URL, please:
https://accounts.google.com/o/oauth2/auth?access_type=offline&client_id=...
Code:
こちらはコマンド実行時に返ってきたURLにブラウザからアクセスすることで、Googleドキュメントを管理しているGoogleアカウントでの認証をすることができます。
認証を行うとキーコードが表示されるのでそちらを Code の後に入力するとエクスポートを行えます。
エクスポートに成功すると、コマンドを実行したフォルダの直下に以下の構成のフォルダが作成されます。
codelabs-tool（Googleドキュメント内の表の「URL」欄に指定した文字列）
├── codelab.json
├── img（画像ファイルを扱ってる場合）
└── index.html
資料作成 ～MarkDownで作る場合～
特徴
Googleドキュメントで作る場合と比べて、完成イメージを確認するには都度エクスポートをしないといけなかったり、そんなに多くないですがCLaaT特有の書き方があったりするので若干手間と学習コストがかかります。
ただGoogleアカウントの認証が不要だったり、コードをGit管理とかできるので会社の業務で使ったり資料のバージョン管理をしたい場合には嬉しいポイントかもしれません。
あとそこまでやるかは別として、CI/CDもできそうですね。
作り方の概要
1. マークダウンファイルの作成
まずはマークダウンファイルを作ります。
改行コードを「LF」に設定しておかないと改行が認識されないので注意してください。
2. CLaaTのお作法を記入
ファイルを作成したら、メタデータとして頭に以下の内容を記述します。公式の説明はこちら。
summary: 説明文
id: 一意のIDを定義
categories: 任意のカテゴリ
environments: Web、Kioskのいずれかを指定
status: Draft、Published、Deprecated、Hiddenのいずれかを指定
feedback link: フィードバックの送信先
analytics account: GoogleアナリティクスID
3. マークダウンでコンテンツを作成
あとは、基本的にマークダウンです。
CLaaTのポイントしては「見出し１」がページタイトル、「見出し２」がセッションタイトル（各ステップのタイトル）になるので各セッションの中で見出しを付けたい時は見出し３以下を使います。
# ページタイトル
セッションタイトルを記載する場合は Duration を利用することで、そのセッションにかかる時間を表示することができます。
## セッションタイトル
Duration: 0:05:00
他にもCLaaT特有の書き方として「お知らせボックス」や「ダウンロードボタン」などがありきますが、とりあえずここまで書いた内容を押さえておけば最低限の資料は作れるはずです。
CLaaTのマークダウンについて更に詳しく知りたい方は、こちらのREADMEなどを適宜ご覧ください。
作成した資料をエクスポート
エクスポートはコマンドラインで以下のコマンドを実行します。
$ claat export <マークダウンファイル名>
例えば「codelab.md」というファイルで作成した場合は以下のように実行します。
$ claat export codelab.md
すると、コマンドを実行したディレクトリにファイル内で指定したID名のフォルダが生成されます。
codelab-id（自分が指定したID）
├── codelab.json
├── img（画像ファイルを扱ってる場合）
└── index.html
資料を公開する方法
作成した資料は以下の方法でWebページに公開することができます。
- Github Pages（*.github.io）
- Google App Engine
- Firebase Hosting
- Google Cloud Storage
- AWS S3
- Netlify
- オープンソースのWebサーバー（Nginx、Apache）
- python -m SimpleHTTPServer（Python 2）
- python3 -m http.server（Python 3）
おわりに
まだ1個サンプルを作ってみただけなので、これからCLaaTをがんがん活用していきたいなと思ってます！
社内で話をしてみたらハンズオンやチュートリアル以外にも動画を埋め込んだセミナー資料作りによさそうとのことだったのでそういったシーンがあれば是非利用を考えてみてください。