GitBookでのブロックチェーンサービスのドキュメント作成

1. 初めに

次世代システム研究室のT.Mです。

今回GMOでブロックチェーンのサービスを提供することとなり、次世代システム研究室はこのサービスの企画から開発まで一貫して関わってきました。

開発したサービスはこちらです。

このサービスはEthereum上にアプリケーションを構築する際に発生する様々な課題を解決するプラットフォームとなりますが、各種の世界初（と思われる）の試みが多数含まれています。

そのためインターネットに情報がなく、サービスを利用される方々にサービス内容を伝えるドキュメントが非常に重要な役割を担います。

今回作成したドキュメントはこちらですが、メンテナンス効率や公開したときの見易さなどを考えてGitBookでのドキュメント作成を行いました。

一般的な使い方はネット上にあふれているため、この記事では、サービスのドキュメント作成時にどのような設定や記述方法が効率的だったかを紹介します。

2. ドキュメント作成で使用した方法の紹介

1 準備

1.1. Bookの作成

GitBookにアクセスし、アカウントを登録した後、対象となるBookを作成します。
ここでは、名称を「TestBook」としておきます。
作成された初期状態が次のような画面になります。

1.2. Branchの作成

この段階で、必要に応じて編集用のブランチを切って、編集用のブランチで作業するようにしましょう。

SnapCrab_NoName_2016-12-28_18-40-9_No-00

1.3. 編集画面の切替

初期状態の画面でも編集は可能ですが、マークダウンに慣れれば、マークダウンでの記述のほうが格段に作業効率が上がります。
上部メニューの「Document Mode」のボタンによって画面の切替を行います。

これによって編集画面が次のようなマークダウン形式に切り替わります。

2. 記述の手順

2.1. 目次の整理

編集効率が最も良い方法は、最初に目次を整理することだと思います。
左メニューのフォルダのマークを選択し、この「TestBook」の実際のファイル構成を表示させます。

SUMMARY.mdファイルを選択し、マークダウンでチャプター階層を作ってみます。
右の画面で状態を確認しながら、リンクの設定を記述します。

今回記述した内容は次の内容になります。

# Summary

* [First Chapter](chapter1.md)
* [Chapter-2](/doc/chapter-2/README.md)
  * [Chapter-2-1](/doc/chapter-2-1/README.md)
* [Chapter-3](/doc/chapter-3/README.md)
  * [Chapter-3-1](/doc/chapter-3-1/README.md)

各記事については、初期状態の最初のサンプル（[First Chapter](chapter1.md)）のようにルートの階層に置いてしまうと、記事が増えたときに乱雑になってしまいます。
上のようにフォルダ形式で階層構造にしておくことをお勧めします。

なお、フォルダは作成しておく必要はありません。
SUMMARY.mdで階層の記述（/doc/chapter-3-1/README.md など）をしておくだけで、後述の「2.2. 内容の記述」時に自動的にフォルダが作成されます。

2.2. 内容の記述

目次の編集が完了した時点で「PUBLISH」を押下して、目次の編集を一旦確定させます。
その後左メニューの表示を切り替えると、先ほど編集したメニューがそのまま表示されるので、後は編集したいページを選択して編集するだけです。

今回はChapter-2-1に次のような記事を記載してみます。

記述した内容は次のような内容です。

# Chapter-2-1

## Chapter-2-1-1

Hello GitBook.

複数ページもどんどん渡り歩きながら編集でき、保存したいタイミングで「PUBLISH」を押下すれば保存されます。

3. プラグインの追加

2016年12月の段階のGitBookでは、初期状態で見出しに対するアンカーの設定はありません。
今回は「TestBook」にアンカーの機能を追加してみます。

まず、左メニューのフォルダ表示画面で右クリックし、「New File」から「book.json」ファイルを作成します。

book.json をに対して下記の記述を追加して、「PUBLISH」をします。

{
  "plugins": [
    "anchorjs"
  ]
}

これで、各見出しに対してアンカーが追加されます。

先ほど作成した、Chapter-2-1 の “Chapter-2-1-1” の項に飛びたい場合は、

[2-1-1](/doc/chapter-2-1/#Chapter-2-1-1)

とすることで、アンカーへの直接のリンクを貼ることができます。

5. まとめ

GitBookでのドキュメント生成で、とても効率的だと思った方法の紹介をさせていただきました。

技術ブログでありながら、技術的な面での内容はほとんどありませんが、今回は作成したドキュメントの内容のほうに技術的な内容が詰まっています。
ぜひこちらを参照して、ブロックチェーンの技術に触れてみてください。

次世代システム研究室では、アプリケーション開発や設計を行うアーキテクトを募集しています。アプリケーション開発者の方、次世代システム研究室にご興味を持って頂ける方がいらっしゃいましたら、ぜひ募集職種一覧からご応募をお願いします。