【GitBook】 オンライン版とCLI版使ってみての比較

hiroaki

自分の主な業務としてAPI仕様書の作成というのがあるのだが、どういうフォーマットで書くか、更新性をもっと高めたい、効率的に書きたいといろいろ試行錯誤している中で、gitbook.comというものに辿りついた。
元々はCLI版として提供されていたものが、近年オンラインサービスとしての展開をはじめたもののようで、これは便利そうということで何件かのプロジェクトで実際に導入してみての感想とCLI版も使ってみての比較などをまとめようと思います。

先に結論から言うと、最新の案件ではCLI版を使用しています。。。
色々と理由があってのことなのですが、これについてもメリット・デメリットの中で言及できればと思います。

オンライン版について

Organization単位でのサブスクリプション形式で、新規でOrganizationを作成してとりあず14日はトライアルとしての使用が可能。
移行はアップグレードしないとフリープランとして扱われ、オンライン編集などの機能が使用できなくなる（github連携を使用することによってドキュメントの更新は可能なのでフリープランでもまぁ使えなくはない）
https://www.gitbook.com/pricing
有料プランは$40/m のTeamプランと$300/mのBusinessプランの２種類で、使用する機能により選択が可能。
チームメンバーに登録している人以外にドキュメントを共有したい場合はShareable linksの機能が必要だが、これはBusinessプランに加入する必要がある。

オンライン版のメリット

オンラインのサービスならではの機能が結構充実していて、使いこなせばかなり

・「Guide」「API」「FAQ」「Changelog」「Blank」など、５種類のテンプレートから記事の作成ができ、記事の要素などもビジュアルエディタを使用することで、簡単にそれっぽいドキュメントがサクっと作れる。MarkdownやHTMLの特別なスキルがなくともそれなりのドキュメントが作成が可能。

・Activitiesから更新内容の確認が可能。更新箇所もハイライト表示できる。また、特定のアクティビティに対してコメントも可能なので gitbook上のみである程度のコミュニケーションをとりながらの編集ができる。

・github連携機能があり、ローカル上でMarkdownファイルを直接編集してプッシュすることでドキュメントの更新が可能になる。
設定はIntegretions のメニューから操作可能。
githubにプッシュするとapp.gitbook.comの画面上にわりと即時で反映されるのはちょっと感動した。

・APIの仕様書を作成するときなんかは、リクエストやパラメーターの項目を予めスタイル設定されたブロックに入力していくだけでいい感じに見やすくまとめられるので便利。CLI版ではこういったプリセットは無い。

・Variantsという機能によってコンテンツのバージョンを即時に切り替え可能。githubでいうところのブランチみたいなもので、仕様のバージョンをver 1, 2 でそれぞれ管理したい場合はこの機能使うとかなり便利。
https://docs.gitbook.com/editing-content/variants
github連携の際に、実際に切り替えたいバージョンをgithubのブランチに紐づけて管理することも可能。

・ビジュアルエディタを用いれば専門的な知識がなくとも容易に編集が可能なので、プロジェクトマネージャーのような人たちにも気軽に使ってもらえると思う。

オンライン版のデメリット

・ビジュアルエディタで特定のフィールドに日本語入力しようとするとバグって入力できない場合がある（結構痛い）

・良いところで、github連携機能が便利と書いたが、たまに githubにプッシュしたドキュメントが反映されない現象がたまに起こる。どういう条件で発生するかが不明なのだが、地味につらい。
Integretionsからgithubの連携を一旦解除して、再度設定しなおすことで改善したりするのだが、いちいち設定しなおすのはかなり面倒。

・ビジュアルエディタでの編集はメリットではあるのだけど、同じような記述を複数のドキュメントに反映したい場合はかなり面倒。テキストエディタでMarkdownを直接してコピペしたほうが断然早いので量産系にはあまり向いてない気がする。

・自分の場合はgithub機能を使用してMarkdownファイルを直接編集するという方法をとっているのだが、基本的にサービス独自に定義されたコードブロックを記述しないといけなくて、これが慣れるまで結構つらい。
↓こんな感じ

{% api-method method="put" host="https://api.xxxx.app" path="/v1/me/user\_attribute/email" %}

{% api-method-summary %}
{% endapi-method-summary %}
{% api-method-description %}
{% endapi-method-description %}
{% api-method-spec %}
{% api-method-request %}
{% api-method-headers %}
{% api-method-parameter name="access\_token" type="string" required=true %}
アクセストークン
{% endapi-method-parameter %}
{% endapi-method-headers %}

また、ローカル上でのプレビュー方法が無いので出力結果はgithubにプッシュしてサービス側に反映されるのを待たないといけないので、細かい箇所の修正の確認とかちょっと面倒。

CLI版について

CLI版のメリット

・基本的にMarkdown形式でガシガシ書いていけるので、個人的には編集しやすい。

・様々なサードパーティプラグインがあり、これを導入することによっていろんな機能拡張が可能。
特に最新の案件ではシーケンス図を使用したりしたかったのだが、これは mermaid 用のプラグインを入れることによって簡単に実現可能。
ただ、このプラグイン複数あり、ちょっとハマりどころがあってので、それについては別記事で述べたい。

・プラグインを使用してPDF書き出しも可能。ファイル化して共有したいときは便利。

・独自CSSの使用が可能。オンライン版みたいなテンプレートによる豊富なビジュアル要素が無いのはデメリットと言えるかもしれないが、独自CSSを使うことによってそれなりにオンライン版に近い見た目を実現することは可能。

CLI版のデメリット

・Markdown、CLIの基本的な操作の知識（必要な場合CSS、HTML）などちょっとした専門知識が

・デプロイ環境は独自に用意する必要がある。サービス版はホスティング込みなので、そう考えるとお得な面もある。
現在の案件では Firebase Hostingを使ったのだが、これについては別途記事化したい。

・一番大きいところとして、Gitbookが現状オンラインサービスを主体としたものに移行しているので、CLI版はもはやアップデートされていない。
最終更新が4 years agoとなっている。。


この記事が気に入ったらサポートをしてみませんか？