📚️
講義資料の運用を DX する（その1）

2024/07/03に公開
Git
 はじめに※以前別の場所で書いた記事の移植です．
現状（すでに過去），講義は講義資料（スライドを PDF にしたもの）とサンプルコードで進めているが，下記で述べるような数多くの問題が発生している．
クラス数が少ないうちは人力で対応することができるが，オンラインオフライン混在で多くのクラスが同時進行する状況で手が回らなくなっている状況にあった．
したがって，「状況に関わらず同質な講義が提供できる」「受講生講師チューターが楽をできる」「持続可能である」仕組みを考案して実現することとした．以下はその試行錯誤の記録である．
前半（この記事）
後半

 今回の DX今回の DX （前半）により，下記の状況を達成する．
テキスト主体の構成を採用することで，PDF によって発生する講義資料の不具合解消．
オンラインデプロイ方式による講義資料へのアクセス改善．
GitHub Actions を用いた講義資料とサンプルコードの管理や展開の簡略化．

 成果物本ページで考案した仕組みを組み込んだサンプルを作成した．
講義資料はスライドから HTML に変更し，サンプルコードは資料内のダウンロードリンクからワンクリックでダウンロードが可能だ．
受講生は，デプロイ先の URL にアクセスするだけで受講に必要な情報にアクセスすることができるようになった．
マスタデータのリポジトリ
クラス 1 （全ての講義を終えた状態を想定）
リポジトリ
デプロイ
クラス 2 （JavaScript 2 回のみを終えた状態を想定）
リポジトリ
デプロイ

 現状: PDF で講義資料を配布現在の講義資料とサンプルコードの展開は以下の手順を必要としている．
講義資料（スライド）を作成する．
サンプルコードと同じディレクトリに入れる．
上記ディレクトリを圧縮する．
圧縮したディレクトリを Google ドライブの共有フォルダに保存する．
共有フォルダから zip ファイルをダウンロードする．
zip ファイルを解凍する．

 課題: 管理やコードで問題が起きる以下のように，全員不幸になるタイミングが数多く報告されている．
スライドからコードをコピーした場合に予期せぬエラーが発生する．
講義中，慣れないスペルの場合はコードの一部をコピーしたほうが無難なケースも多い．
主に PDF の改行が原因でエディタ上でエラーが発生する場合がある．
「コードは間違っていないのに何故か動かない」状況が発生し，全員不幸になる．
レイアウトの制約上スライドとコードの区切りが整合しない．
中途半端な区切りやフォントの縮小など望ましくないコードを掲載せざるを得ない場合がある．
コードブロックが改ページで寸断されることで流れが不透明になる．
括弧の対応が不透明になり，タイプミスも増える．
解説する方もされる方も混乱しやすく，全員不幸になる．
講義資料（スライド）の修正時の工数が多い．
スライドを修正する．
共有フォルダに保存する．
ダウンロードする．
解凍する．
旧バージョンを削除する．
その場で修正することができない．
講師受講生双方の手順が煩雑で，全員不幸になる．
スライドとサンプルコードを個別に管理しなければならない．
ファイル名修正などが発生すると双方修正し，再度展開が必要．
上記のスライドと同様の工数が発生する．
記述に齟齬が発生して混乱し，全員不幸になる．
資料の展開を任意のタイミングで行えない．
講義直前に上記のフローを実行する必要がある．
準備しておいて 1 つの動作で展開する，などができない．
行動が時間に束縛され，全員不幸になる．
以前の講義内容（資料）を見たい場合，別ファイルを探してアクセスする必要がある．
自分でファイル及びサンプルコードを管理する必要がある．
見失った場合，再度ダウンロードの手順を踏まなければならない．
煩雑なファイル管理や命名規則が発生し，全員不幸になる．

 課題の解決策: PDF をやめてテキストにする各課題に対して，下記のようなアプローチで検討した．
スライドからコードをコピーした場合に予期せぬエラーが発生する．

レイアウトの制約上スライドとコードの区切りが整合しない．
→ PDF ではなく，テキストベースの資料とする．
講義資料（スライド）の修正時の工数が多い．
→ ファイルの配布でなく，デプロイして URL を閲覧する形式とする．
スライドとサンプルコードを個別に管理しなければならない．
→ 講義資料とサンプルコードを合わせてデプロイし，両者を紐付ける．
資料の展開を任意のタイミングで行えない．
→ PC，モバイルを問わずデプロイが可能な環境を構築する．
以前の講義内容（資料）を見たい場合，別ファイルを探してアクセスする必要がある．
→ 全ての資料を同じ URL にデプロイすることで，いつでも過去の資料を閲覧できる状態にする．

 mdbook + GitHub + GitHub Actions で解決する上記の解決策を実現するため，下記の技術を用いることとした．
SSG「mdbook」を用いて講義資料作成する．
テキスト主体の資料．
全ての講義資料を同じ URL にデプロイ．
GitHub を用いて講義資料とデプロイの管理を行う．
講義資料のデプロイ．
PC，モバイル問わないデプロイ環境の整備．
GitHub Actions を用いてサンプルコード圧縮とデプロイを行う．
講義資料とサンプルコードの紐づけ．
サンプルコードをワンクリックでダウンロード．

 現時点で実現を目指すフローマスターとなる講義資料とサンプルコードを事前に準備しておく．
新しいクラスが開始するタイミングで講義資料用のリポジトリを準備する．
マスターの資料からクローンし，vs code 上でクラス毎にユニークとなる部分やデプロイ範囲を設定する．
GitHub にディレクトリを push する．
GitHub 上で main ブランチにマージする．
（自動）GitHub Actions を用いて資料をビルドする
（自動）サンプルコードを zip 圧縮し，講義資料とマージする．
（自動）ビルド完了後，GitHub Pages を用いて自動でデプロイされる．
（デプロイ URL は予め受講生に共有しておく．）
デプロイされた資料からワンクリックでサンプルコードがダウンロードできる．
以降，講義準備時は毎回 3-5 を行うのみ．
これらの実現により，
受講生は資料のファイル管理や捜索から開放され，コードを書くことに専念できる．
講師側は不毛なスライド作成（個人の感想）から開放されてエディタと GitHub で全てが可能となる．
チューターは毎回資料をダウンロードすることなく，予め指定された URL を押さえておけばすぐに講義に入ることができる．
つまり，全員が幸せになる．そして，フローを自作することが GEEK だ．
以下に詳細な内容を紹介する．

 SSG「mdbook」を用いた講義資料作成「mdbook」は Rust 製の SSG フレームワークである．SSG を実現するフレームワークは数多くあるが，ドキュメント生成ツールとしての機能が必要十分であることと，筆者が Rust が好きという理由で採用した．
特徴は下記のとおり．
md ファイルで各ファイルを作成する．ビルド後はそれぞれが HTML ファイルとしてデプロイされる．
目次となる md ファイルが存在する．これを操作することで公開する範囲を設定することができる．
テーマの切り替えや JavaScript や PHP のシンタックスハイライトに対応しており，素の状態で十分見やすい．
レスポンシブ対応済．
GitHub Actions を用いたデプロイのサンプルが準備されている．
ここでは特に変わった処理は必要ない．各講義毎にディレクトリを作成し，区切り毎に md ファイルをつくって解説を書いていくだけだ．
これを実現することで，謎の改行やページ区切りで混乱する苦行やファイルを管理する面倒な操作を過去のものとした．
やはり時代はテキストだ．環境に依存せず移植が容易なテキストこそ至高である．

 GitHub を用いた講義資料とデプロイの管理GitHub Actions 用の yml ファイル内にデプロイのフローを記述することで GitHub Pages 上にデプロイすることが可能となる．
より具体的には，下記の流れでフローが実行される．
「main」ブランチに push されたタイミングでビルドコマンドを実行する．
「ビルドコマンドにより吐き出されたファイルがまとめられているディレクトリ」を「gh-pages」ブランチに push する．
GitHub Pages に「gh-pages」ブランチをデプロイする．
実際の yml ファイルは以下のような記述となる（mdbook 公式のサンプルほぼそのまま）．
name: github pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
        with:
          mdbook-version: "0.4.8"
          # mdbook-version: 'latest'

      # mdファイルのビルド
      - run: mdbook build

      # ビルドされたファイル群をgh-pagesブランチにデプロイ
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book
講師は下記手順で講義資料の準備を行うこととなる．
develop ブランチで講義資料を準備する．
準備ができ次第，main ブランチへプルリクエストを送る．
任意のタイミングで main ブランチへのマージを行うことで，上記のフローが実行され，資料がデプロイされる．（マージ操作はモバイルのアプリケーションからでも実行することができる点がポイント）
これを実現することで，毎回の PDF 作成 → アップロードの手順や修正に伴う煩雑な作業を駆逐することができた．

 GitHub Actions を用いたサンプルコード圧縮とデプロイ上記のフローでは，講義資料そのものはデプロイができるが，サンプルコードが含まれていない．
このままではサンプルコードは別途 Google ドライブなどに共有する必要がある．これでは，今回の狙いの半分しか達成されていない状況だ．
したがって，ビルドと同時にサンプルコードを zip 形式に圧縮し，デプロイするファイルにマージする処理が必要である．
しかし，これも GitHub Actions 内で実行可能だ．
yml ファイルに下記の処理を追加した．やっていることは必要な処理をシェルコマンドで実行しているだけである．
name: github pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
        with:
          mdbook-version: "0.4.8"
          # mdbook-version: 'latest'

      - run: mdbook build

      # 🔽 サンプルファイルをzip圧縮してビルドしたファイル群に追加する処理
      - run: |
          mkdir ./book/samples
          cd samples
          find . \! -name '*.zip' -type d -exec zip -r {}.zip {} \;
          mv *.zip ../book/samples

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book
これにより，zip 圧縮されたサンプルコードのファイルが自動でデプロイされるようになった．
あとは，講義資料側に「zip ファイルのパスを指定したリンク」を設定しておけばワンクリックで zip ファイルをダウンロード可能である．
これを実現することで，講義の度に毎回 Google ドライブにアクセスするという面倒な手順をスキップできるようになった．

 まとめと次の課題今回の DX により，下記の状況を達成することができた．
テキスト主体の構成を採用することで，PDF によって発生する講義資料の不具合解消．
オンラインデプロイ方式による講義資料へのアクセス改善．
GitHub Actions を用いた講義資料とサンプルコードの管理や展開の簡略化．
しかし，実使用した結果，下記の課題が残っていることが判明した．
新規クラスが開講する度に新しいリポジトリの作成が必要となる．
内容の修正が必要な場合，クラス資料とマスタデータの異なるリポジトリで更新作業が必要となる．
複数の人間が講師を務める場合，お互いの修正を円滑に反映することができない．
これでは持続可能な体勢とは言えないので，まだ改善が必要である．．！
講義資料の運用を DX する（その 2）へ続く．．．
GitHubで編集を提案
はじめに

今回の DX

成果物

現状: PDF で講義資料を配布

課題: 管理やコードで問題が起きる

課題の解決策: PDF をやめてテキストにする

mdbook + GitHub + GitHub Actions で解決する

現時点で実現を目指すフロー

SSG「mdbook」を用いた講義資料作成

GitHub を用いた講義資料とデプロイの管理

GitHub Actions を用いたサンプルコード圧縮とデプロイ

まとめと次の課題

Discussion
