技術書のサポートサイトを作ろう！
先日、私個人としては初の単書となる「からあげ先生のとにかく楽しいAI自作教室」が発売となりました（詳細は以下記事参照ください）。
技術書（技術的な内容の書籍）では、書籍のコードをダウンロードしたり、質問などができるサポートサイトを用意することが多いです。従来は、出版社が用意することが一般的だったのですが、最近はライブラリのアップデートに伴う早いサイクルでのコードのアップデートの対応、質問や誤記訂正への早い対応のために、作者個人がサポートサイトを用意することが多くなりました。私の書籍でも、私がGitHub上に作成したリポジトリをサポートサイトとして運用しています。以下となります。
また、商業誌以外の、技術同人誌などの個人での発行物に関しては、当然サポートサイトは（必要であれば）自分で作成することになります。書籍の作り方に関する情報は多くありますが、技術書のサポートサイトの作り方の情報は、あんまりなかったので、ここにまとめておこうと思います。技術書のサポートサイト作る人は参考にしてみてください。技術書以外の書籍でも、参考になる点あるかもしれません。
サポートサイトはGitHubに作るのがおすすめ
技術書の場合、サポートサイトはGitHubに作るのがおすすめです。理由は以下です。
- 書籍が増えた時、リポジトリを増やすことで対応できる
- 技術書を読むような人が（ジャンルにはよりますが）GitHub/Gitに慣れている
- Google Colabのノートブックのバックアップ/実行に対応している
- 読者からのフィードバックをissueやPull Requestという形でもらうことができる
- 出版社の編集者・共著者の複数人で管理が可能
なお、そもそもGit/GitHubって何？という人は以下記事参照ください。
サポートサイトのおすすめのフォーマット
READMEには、以下くらいを書くと良いのかなと思っています。
- 書籍情報
- 書籍のコード・Google Colabノートブック
- 正誤表・FAQ（GitHub Issueの活用）
- 参考書籍・参考サイト・論文
- 筆者情報
- ライセンス
なお、記載内容に関しては以下のサポートサイトのリポジトリを参考にしました。
それぞれ簡単に説明していきます。
書籍情報
書籍の情報として、購入先・書籍の内容を書きます。これ省略しているサポートサイトも結構あるのですが、少数ですがサポートサイトから書籍を知る人もいるかもしれないので、最初に本の情報をしっかり書いておいた方が良いと思います。
表紙の画像も表示した方が、一目で書籍のサポートサイトと分かるので良いでしょう。購入先は、Amazon, Kindle、楽天、楽天Koboあたりを記載しています（他にもたくさんありますが、キリがないので）。
購入迷う人のために、書籍の紹介やレビュー記事へのリンクもここから貼っています。
書籍のコード・Google Colaboratory ノートブック
書籍のコードは、章ごとにディレクトリに分けて保存しておいて、トップのREAMEからリンクを貼るのが良いかと思います。細かいことですが、表を使って書いた方が「ちゃんと作っている」感があってよいと思います。
Python関係の本だと、初学者が簡単に動かせるようにGoogle Colaboratory（Google Colab）のノートブックを公開する例も多いと思います（Google Colabに関しては以下記事参照ください）。
GitHubだと、Google Colabのノートブックから「ファイル -> GitHubにノートを保存」を使って、簡単に保存することができます。この方法で保存したノートブックには、ノートブックの冒頭に自動でGoogle Colabで開くリンクがつくので便利です。以下記事参照ください。
また、以下のように書くとリポジトリの全てのGoogle ColabのノートブックをGoogle Colabで開けるようなリンクアイコンが作れます。
[](https://colab.research.google.com/github/karaage0703/karaage-ai-book/blob/master)
具体的には以下のようなアイコンです。
上記アイコンクリックすると、以下のようにGoogle ColabでGitHubのノートブックを開くようなダイアログが自動で表示されます。
単純にGoogle Colabのノートブックを共有して、共有リンクを貼っても良いと思います。私は共有リンクもGitHubへのリンクも両方貼り付けています。
正誤表・FAQ
正誤表・FAQに関しては、GitHubのissueのテンプレートを活用します。この後詳細を説明します。
参考書籍・参考サイト・論文
関連情報記載します。書籍に載っている内容でも、リンクがあると読者には親切と思います。
筆者情報
せっかくなので筆者情報も載せておきましょう。ファンが増えるかもしれません（増えるといいな）。
ライセンス
読者に書籍のコードを最大限活用してもらうために、ライセンスも記載しておきましょう。
これを明示しないと、読者がコードを無断で利用すると、筆者から訴えられるリスクを抱えることになります。読者に安心して使ってもらうためにも、きちんとライセンス設定することが親切だと思います。
サポートサイトを作る際のTIPS
正誤表・FAQにGitHubのIssueのテンプレートを活用
誤記訂正や質問に関しては、issueから投稿してもらうようにしています。といっても、GitHub慣れてない人は、issueをどういう風に投稿するかハードル高いと思うので、少しでもハードル下げるためにissueのテンプレートを活用しました。テンプレートの作成方法は、以下の公式情報を参照ください。
リポジトリ用に Issue テンプレートを設定する - GitHub Docs
issueのテンプレートを設定すると、issueの投稿ボタンをクリックすると、以下のようにテンプレートの選択画面が出ます。
例えば誤記の連絡をクリックすると、以下のようにテンプレートが自動で挿入されるので、投稿者が何を書けば良いのか悩まずにすみますし、報告受ける方も、必要な情報をもらえるので助かります。
実際に投稿されたissueです。
誤記訂正のテンプレートからissueを投稿すると、「誤記」というラベルがついて、関係者（著者・編集者）がアサインされるように設定されているので、自動的に整理と通知がされて便利です。
GitHub Pagesを使う
ソフトウェア以外のジャンルの技術書だったり、技術書以外の書籍の場合など、読者にGitHubのインターフェースに慣れ親しんでいる人が少ない場合は、普通のWebサイトらしいサポートページの方が良い場合もあります。
そのときは、GitHub Pagesを使うと、GitHubを使って静的なWebサイトを作成することもできます。詳細は以下参照ください。
GitHub Pagesでも、Issueを使った誤記訂正・質問受け付けなどの機能は活用できるので、うまく組み合わせると良いかと思います。
まとめ
技術のサポートサイトに関して、特にGitHubを活用した作り方を紹介しました。技術書で一番大切なのは、もちろん書籍自体の内容ですが、最近はコードの量自体が多かったり、アップデートが必要だったりと、よりサポートサイトの重要性が増していると感じていますので、書籍を作った後に慌てて作るより、書籍と一緒に作り上げるくらいの気持ちが良いのではないかなと思っています。
既にサポートサイト、たくさんフィードバックもいただき嬉しい限りです。誤記の報告は、ちょっと落ち込みますが、それだけしっかり読んでくれる読者が多いということと、正誤表まとめることが他の読者のメリットにもなると思い前向きに捉えています。
また、書籍にも書いたのですが、今後のサポートサイトのあり方として、書籍を読んだ読者が書籍を参考に新たなプログラムをサポートサイトにPull Requestして、一緒に書籍をアップデートしてくような動きも面白いのじゃないかなと考えています。アウトプットすることは、読者の学びにもなると思います。
サポートサイトに関しては、実は書籍が無くても参考になるくらい充実させていますが、もしよろしければ書籍も一緒に楽しんでいただけましたら幸いです。
Amazon
- 作者:からあげ
- 発売日: 2021/01/08
- メディア: 単行本
Kindle
- 作者:からあげ
- 発売日: 2020/12/22
- メディア: Kindle版
