<p>技術書典16に参加予定の皆さま、進捗はいかがですか。私はまだ一行も書いていません。ゴールデンウィーク中にがんばります。</p>
<p>さて、技術書典ではRe:VIEWを使って執筆している方が多いのではないでしょうか。今回はじめてRe:VIEWを使って製品マニュアルを作ってみたら、かなり体験がよかったので、手順をご紹介します。</p>
<h2 id="re%3Aview%E3%81%A7%E8%A3%BD%E5%93%81%E3%83%9E%E3%83%8B%E3%83%A5%E3%82%A2%E3%83%AB%E3%82%92%E4%BD%9C%E3%82%8B%E3%83%A1%E3%83%AA%E3%83%83%E3%83%88">
<a class="header-anchor-link" href="#re%3Aview%E3%81%A7%E8%A3%BD%E5%93%81%E3%83%9E%E3%83%8B%E3%83%A5%E3%82%A2%E3%83%AB%E3%82%92%E4%BD%9C%E3%82%8B%E3%83%A1%E3%83%AA%E3%83%83%E3%83%88" aria-hidden="true"></a> Re:VIEWで製品マニュアルを作るメリット</h2>
<p>本記事の手順には、以下のメリットがあります。</p>
<ul>
<li>書籍のような見栄えの製品マニュアルを作れる</li>
<li>Markdownで執筆できるので、学習コストが低く、原稿を再利用しやすい</li>
<li>textlintやprhによる自動校正ができる</li>
<li>GitHub Copilotによる自動補完ができる（契約している場合）</li>
</ul>
<h2 id="re%3Aview%E3%81%A8%E3%81%AF">
<a class="header-anchor-link" href="#re%3Aview%E3%81%A8%E3%81%AF" aria-hidden="true"></a> Re:VIEWとは</h2>
<p>Re:VIEWは、Re:VIEW記法やMarkdownなどのテキストフォーマットからPDFやEPUBなどの電子書籍を生成するツールです。Rubyで書かれており、Rubyのgemとして提供されています。技術書典では、<a href="https://kauplan.org/reviewstarter/" target="_blank" rel="nofollow noopener noreferrer">Re:VIEW Starter</a>と<a href="https://github.com/TechBooster/ReVIEW-Template" target="_blank" rel="nofollow noopener noreferrer">ReVIEW-Template</a>の2つのテンプレートがよく使われているのを見かけます。</p>
<p>私はReVIEW-Templateを自分用にカスタマイズした<a href="https://github.com/sikkimtemi/book_ReVIEW_Template" target="_blank" rel="nofollow noopener noreferrer">テンプレート</a>を使っています。デフォルトのReVIEW-Templateは、EPUB形式で出力したときのコードブロックの見た目がいまいちだったので、CSSを修正しました。これにより、Kindle Direct Publishingで出版したときの違和感が低減しました（今回はあまり関係ありませんが）。また、最初からMarkdownで執筆できるように、<code>config.yml</code>を修正しました。</p>
<h2 id="%E3%83%9E%E3%83%8B%E3%83%A5%E3%82%A2%E3%83%AB%E4%BD%9C%E6%88%90%E6%89%8B%E9%A0%86">
<a class="header-anchor-link" href="#%E3%83%9E%E3%83%8B%E3%83%A5%E3%82%A2%E3%83%AB%E4%BD%9C%E6%88%90%E6%89%8B%E9%A0%86" aria-hidden="true"></a> マニュアル作成手順</h2>
<h3 id="%E4%BA%8B%E5%89%8D%E6%BA%96%E5%82%99">
<a class="header-anchor-link" href="#%E4%BA%8B%E5%89%8D%E6%BA%96%E5%82%99" aria-hidden="true"></a> 事前準備</h3>
<p>あらかじめDockerとVSCodeをインストールしておいてください。textlintやprhの校正機能を使いたい場合は、node.jsとVSCodeの拡張機能(vscode-textlintとprh-ProofReadingHelper)もインストールしてください。</p>
<h3 id="%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AE%E3%83%80%E3%82%A6%E3%83%B3%E3%83%AD%E3%83%BC%E3%83%89">
<a class="header-anchor-link" href="#%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88%E3%81%AE%E3%83%80%E3%82%A6%E3%83%B3%E3%83%AD%E3%83%BC%E3%83%89" aria-hidden="true"></a> テンプレートのダウンロード</h3>
<p><a href="https://github.com/sikkimtemi/book_ReVIEW_Template" target="_blank" rel="nofollow noopener noreferrer">こちら</a>からテンプレートをダウンロードして、VSCodeで開いてください。</p>
<div class="code-block-container"><pre class="language-zsh"><code class="language-zsh">git clone https://github.com/sikkimtemi/book_ReVIEW_Template.git
cd book_ReVIEW_Template
code .
</code></pre></div><h3 id="%E5%8B%95%E4%BD%9C%E7%A2%BA%E8%AA%8D">
<a class="header-anchor-link" href="#%E5%8B%95%E4%BD%9C%E7%A2%BA%E8%AA%8D" aria-hidden="true"></a> 動作確認</h3>
<p>まずは、ダウンロードした状態でPDFをビルドしてみましょう。Re:VIEWはテキストファイルの原稿をコンパイルすることで、PDFやEPUBなどの電子書籍を生成します。</p>
<div class="code-block-container"><pre class="language-zsh"><code class="language-zsh">REVIEW_CONFIG_FILE=config-ebook.yml ./build-in-docker-pdf.sh
</code></pre></div><p>Dockerが動作する環境であれば、問題なくPDFが生成されるはずです。PDFは<code>articles</code>ディレクトリに出力されます。</p>
<div class="code-block-container"><pre class="language-zsh"><code class="language-zsh">open articles/Book_ReView_Template.pdf # macOSの場合
</code></pre></div><p><img src="https://res.cloudinary.com/zenn/image/fetch/s--XGNzfLFx--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_1200/https://storage.googleapis.com/zenn-user-upload/deployed-images/f96892394b92ffb4c54a4be8.png%3Fsha%3D6eca8117a7047aa9507a5c03ba3e7d61653f9695" alt="生成されたPDF" loading="lazy" class="md-img"><br>
<em>生成されたPDF</em></p>
<h3 id="config.yml%E3%81%AE%E4%BF%AE%E6%AD%A3">
<a class="header-anchor-link" href="#config.yml%E3%81%AE%E4%BF%AE%E6%AD%A3" aria-hidden="true"></a> config.ymlの修正</h3>
<p>製品マニュアルらしくなるように、<code>articles/config.yml</code>を修正しましょう。私が先日書いたマニュアルでは、以下の箇所を修正しました。</p>
<ul>
<li>署名(booktitle)の修正</li>
<li>著者名(aut)をコメントアウト</li>
<li>edtにチーム名（部署名）を設定</li>
<li>pblに会社名を設定</li>
<li>dateにリリース日を設定</li>
<li>historyを修正</li>
<li>rightsに著作権情報を設定</li>
<li>urnidを修正</li>
</ul>
<p>config.ymlを修正したら、再度PDFをビルドして、修正箇所が反映されていることを確かめましょう。</p>
<h3 id="catalog.yml%E3%81%AE%E4%BF%AE%E6%AD%A3">
<a class="header-anchor-link" href="#catalog.yml%E3%81%AE%E4%BF%AE%E6%AD%A3" aria-hidden="true"></a> catalog.ymlの修正</h3>
<p>デフォルトの<code>articles/catalog.yml</code>は、次のようになっています。</p>
<div class="code-block-container"><pre class="language-yaml"><code class="language-yaml"><span class="token key atrule">PREDEF</span><span class="token punctuation">:</span>
  <span class="token punctuation">-</span> 0_opening.re

<span class="token key atrule">CHAPS</span><span class="token punctuation">:</span>
  <span class="token punctuation">-</span> 1_chapter1.re
  <span class="token punctuation">-</span> 2_chapter2.re

<span class="token key atrule">APPENDIX</span><span class="token punctuation">:</span>

<span class="token key atrule">POSTDEF</span><span class="token punctuation">:</span>
  <span class="token punctuation">-</span> 3_ending.re
  <span class="token punctuation">-</span> contributor.re
</code></pre></div><p>製品マニュアルにあとがきや著者紹介は不要なので、次のように書き換えましょう。</p>
<div class="code-block-container"><pre class="language-yaml"><code class="language-yaml"><span class="token key atrule">PREDEF</span><span class="token punctuation">:</span>
  <span class="token punctuation">-</span> 0_opening.re

<span class="token key atrule">CHAPS</span><span class="token punctuation">:</span>
  <span class="token punctuation">-</span> 1_chapter1.re
  <span class="token punctuation">-</span> 2_chapter2.re

<span class="token key atrule">APPENDIX</span><span class="token punctuation">:</span>

<span class="token key atrule">POSTDEF</span><span class="token punctuation">:</span>
</code></pre></div><p>書き換えたら、再度PDFをビルドしてください。あとがきと著者紹介がなくなっていればOKです。</p>
<h3 id="%E5%8E%9F%E7%A8%BF%E3%81%AE%E4%BD%9C%E6%88%90">
<a class="header-anchor-link" href="#%E5%8E%9F%E7%A8%BF%E3%81%AE%E4%BD%9C%E6%88%90" aria-hidden="true"></a> 原稿の作成</h3>
<p>それでは、製品マニュアルの原稿を作成しましょう。まずは、<code>articles/0_opening.md</code>を修正してみましょう。ここで注意しなければいけないのは、<code>articles/_refiles/0_opening.re</code>には手を加えないことです。Re:VIEWは、MarkdownをRe:VIEW記法に変換する際、<code>articles/_refiles</code>ディレクトリに一時ファイルを生成します。このファイルは、ビルド時に削除されるので、修正しても意味がありません。</p>
<p><code>articles/0_opening.md</code>を修正したら、再度PDFをビルドしてください。修正箇所がPDFに反映されていればOKです。これで原稿を書く準備は整いました。ゴリゴリ書いていきましょう。画像は<code>articles/images</code>ディレクトリに格納してください。</p>
<p>マークダウンファイルを追加したら、<code>catalog.yml</code>にも追記してください。原稿を書く対象は、拡張子が<code>.md</code>のマークダウンファイルですが、<code>catalog.yml</code>に記載するのは、拡張子が<code>.re</code>のRe:VIEW記法ファイルです。間違えないように注意しましょう。</p>
<p>余談ですが、<a href="https://nextpublishing.jp/book-series/%e6%8a%80%e8%a1%93%e3%81%ae%e6%b3%89%e3%82%b7%e3%83%aa%e3%83%bc%e3%82%ba" target="_blank" rel="nofollow noopener noreferrer">技術の泉</a>に入稿する場合のファイル形式は、Re:VIEW形式です。私は毎回、<code>articles/_refiles</code>ディレクトリに生成されたRe:VIEW形式のファイルをコピーして、入稿用のリポジトリにアップロードしています。</p>
<h3 id="%E8%A1%A8%E7%B4%99%E7%94%BB%E5%83%8F%E3%81%AE%E5%B7%AE%E3%81%97%E6%9B%BF%E3%81%88">
<a class="header-anchor-link" href="#%E8%A1%A8%E7%B4%99%E7%94%BB%E5%83%8F%E3%81%AE%E5%B7%AE%E3%81%97%E6%9B%BF%E3%81%88" aria-hidden="true"></a> 表紙画像の差し替え</h3>
<p>表紙の画像は<code>articles/images/cover.png</code>です。B5サイズを想定しているので、182mm x 257mmの画像を用意して差し替えてください。私は、<a href="https://www.canva.com/" target="_blank" rel="nofollow noopener noreferrer">Canva</a>を使って表紙画像を作成しました。</p>
<h3 id="%E5%AE%8C%E6%88%90%E3%81%97%E3%81%9F%E8%A3%BD%E5%93%81%E3%83%9E%E3%83%8B%E3%83%A5%E3%82%A2%E3%83%AB">
<a class="header-anchor-link" href="#%E5%AE%8C%E6%88%90%E3%81%97%E3%81%9F%E8%A3%BD%E5%93%81%E3%83%9E%E3%83%8B%E3%83%A5%E3%82%A2%E3%83%AB" aria-hidden="true"></a> 完成した製品マニュアル</h3>
<p>今回、実際に作成した製品マニュアルは、<a href="https://drive.google.com/file/d/1Iq1mn9a55UF5_i2WKpTFGVC6gTk9AQTm/view?usp=sharing" target="_blank" rel="nofollow noopener noreferrer">システムガイド</a>と<a href="https://drive.google.com/file/d/1c-obMd2orVBppb-_MWI0zB9xWut6PUXo/view?usp=sharing" target="_blank" rel="nofollow noopener noreferrer">ユーザーガイド</a>の2つです。作成に要した時間は、システムガイドが2日、ユーザーガイドが1日でした。テンプレートを活用することで原稿の作成に集中でき、効率的に作業できました。</p>
<h2 id="%E5%8E%9F%E7%A8%BF%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%AE%E6%B4%BB%E7%94%A8">
<a class="header-anchor-link" href="#%E5%8E%9F%E7%A8%BF%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%AE%E6%B4%BB%E7%94%A8" aria-hidden="true"></a> 原稿ファイルの活用</h2>
<p>この手順でマニュアルを作成すると、成果物としてMarkdown形式の原稿ファイルが手元に残ります。Markdown形式のファイルは使い勝手がよいので、例えば次のようなドキュメントサイトを簡単に作ることができます。</p>
<p><span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__51dd16529b66e" src="https://embed.zenn.studio/card#zenn-embedded__51dd16529b66e" data-content="https%3A%2F%2Fcrm-mailmanager.netlify.app%2F" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://crm-mailmanager.netlify.app/" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://crm-mailmanager.netlify.app/</a></p>
<p>このページは実際に、1日かからずに作成できました。これも面白い体験だったので、別の記事にまとめる予定です。</p>
<h2 id="%E3%81%BE%E3%81%A8%E3%82%81">
<a class="header-anchor-link" href="#%E3%81%BE%E3%81%A8%E3%82%81" aria-hidden="true"></a> まとめ</h2>
<p>Re:VIEWを使って製品マニュアルを作る手順をご紹介しました。Re:VIEWは、Markdownで執筆できるので、学習コストが低く、原稿を再利用しやすいのがメリットです。技術書を執筆する以外にも、こんな使い道があったんですね。ぜひ参考にしてみてください。</p>


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

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

Discussion