Zenn
📕

Re:VIEWとMarkdownで製品マニュアルを作ってみた

2024/04/05に公開
#
review
#
技術書典
tech

技術書典16に参加予定の皆さま、進捗はいかがですか。私はまだ一行も書いていません。ゴールデンウィーク中にがんばります。

さて、技術書典ではRe:VIEWを使って執筆している方が多いのではないでしょうか。今回はじめてRe:VIEWを使って製品マニュアルを作ってみたら、かなり体験がよかったので、手順をご紹介します。

Re:VIEWで製品マニュアルを作るメリット

本記事の手順には、以下のメリットがあります。

  • 書籍のような見栄えの製品マニュアルを作れる
  • Markdownで執筆できるので、学習コストが低く、原稿を再利用しやすい
  • textlintやprhによる自動校正ができる
  • GitHub Copilotによる自動補完ができる（契約している場合）

Re:VIEWとは

Re:VIEWは、Re:VIEW記法やMarkdownなどのテキストフォーマットからPDFやEPUBなどの電子書籍を生成するツールです。Rubyで書かれており、Rubyのgemとして提供されています。技術書典では、Re:VIEW StarterとReVIEW-Templateの2つのテンプレートがよく使われているのを見かけます。

私はReVIEW-Templateを自分用にカスタマイズしたテンプレートを使っています。デフォルトのReVIEW-Templateは、EPUB形式で出力したときのコードブロックの見た目がいまいちだったので、CSSを修正しました。これにより、Kindle Direct Publishingで出版したときの違和感が低減しました（今回はあまり関係ありませんが）。また、最初からMarkdownで執筆できるように、config.ymlを修正しました。

マニュアル作成手順

事前準備

あらかじめDockerとVSCodeをインストールしておいてください。textlintやprhの校正機能を使いたい場合は、node.jsとVSCodeの拡張機能(vscode-textlintとprh-ProofReadingHelper)もインストールしてください。

テンプレートのダウンロード

こちらからテンプレートをダウンロードして、VSCodeで開いてください。

git clone https://github.com/sikkimtemi/book_ReVIEW_Template.git
cd book_ReVIEW_Template
code .

動作確認

まずは、ダウンロードした状態でPDFをビルドしてみましょう。Re:VIEWはテキストファイルの原稿をコンパイルすることで、PDFやEPUBなどの電子書籍を生成します。

REVIEW_CONFIG_FILE=config-ebook.yml ./build-in-docker-pdf.sh

Dockerが動作する環境であれば、問題なくPDFが生成されるはずです。PDFはarticlesディレクトリに出力されます。

open articles/Book_ReView_Template.pdf # macOSの場合

生成されたPDF
生成されたPDF

config.ymlの修正

製品マニュアルらしくなるように、articles/config.ymlを修正しましょう。私が先日書いたマニュアルでは、以下の箇所を修正しました。

  • 署名(booktitle)の修正
  • 著者名(aut)をコメントアウト
  • edtにチーム名（部署名）を設定
  • pblに会社名を設定
  • dateにリリース日を設定
  • historyを修正
  • rightsに著作権情報を設定
  • urnidを修正

config.ymlを修正したら、再度PDFをビルドして、修正箇所が反映されていることを確かめましょう。

catalog.ymlの修正

デフォルトのarticles/catalog.ymlは、次のようになっています。

PREDEF:
  - 0_opening.re

CHAPS:
  - 1_chapter1.re
  - 2_chapter2.re

APPENDIX:

POSTDEF:
  - 3_ending.re
  - contributor.re

製品マニュアルにあとがきや著者紹介は不要なので、次のように書き換えましょう。

PREDEF:
  - 0_opening.re

CHAPS:
  - 1_chapter1.re
  - 2_chapter2.re

APPENDIX:

POSTDEF:

書き換えたら、再度PDFをビルドしてください。あとがきと著者紹介がなくなっていればOKです。

原稿の作成

それでは、製品マニュアルの原稿を作成しましょう。まずは、articles/0_opening.mdを修正してみましょう。ここで注意しなければいけないのは、articles/_refiles/0_opening.reには手を加えないことです。Re:VIEWは、MarkdownをRe:VIEW記法に変換する際、articles/_refilesディレクトリに一時ファイルを生成します。このファイルは、ビルド時に削除されるので、修正しても意味がありません。

articles/0_opening.mdを修正したら、再度PDFをビルドしてください。修正箇所がPDFに反映されていればOKです。これで原稿を書く準備は整いました。ゴリゴリ書いていきましょう。画像はarticles/imagesディレクトリに格納してください。

マークダウンファイルを追加したら、catalog.ymlにも追記してください。原稿を書く対象は、拡張子が.mdのマークダウンファイルですが、catalog.ymlに記載するのは、拡張子が.reのRe:VIEW記法ファイルです。間違えないように注意しましょう。

余談ですが、技術の泉に入稿する場合のファイル形式は、Re:VIEW形式です。私は毎回、articles/_refilesディレクトリに生成されたRe:VIEW形式のファイルをコピーして、入稿用のリポジトリにアップロードしています。

表紙画像の差し替え

表紙の画像はarticles/images/cover.pngです。B5サイズを想定しているので、182mm x 257mmの画像を用意して差し替えてください。私は、Canvaを使って表紙画像を作成しました。

完成した製品マニュアル

今回、実際に作成した製品マニュアルは、システムガイドとユーザーガイドの2つです。作成に要した時間は、システムガイドが2日、ユーザーガイドが1日でした。テンプレートを活用することで原稿の作成に集中でき、効率的に作業できました。

原稿ファイルの活用

この手順でマニュアルを作成すると、成果物としてMarkdown形式の原稿ファイルが手元に残ります。Markdown形式のファイルは使い勝手がよいので、例えば次のようなドキュメントサイトを簡単に作ることができます。

https://crm-mailmanager.netlify.app/

このページは実際に、1日かからずに作成できました。これも面白い体験だったので、別の記事にまとめる予定です。

まとめ

Re:VIEWを使って製品マニュアルを作る手順をご紹介しました。Re:VIEWは、Markdownで執筆できるので、学習コストが低く、原稿を再利用しやすいのがメリットです。技術書を執筆する以外にも、こんな使い道があったんですね。ぜひ参考にしてみてください。

Discussion