aptpod Advent Calendar 2019の19日目担当、Webチームの蔵下です。普段は、自社プロダクトのUIをReactでゴリゴリ書きつつ、社内のお酒好きを集めて不定期で飲み会を開いています🍶（飲みのお誘いお待ちしています）
みなさんの会社では誰がユーザーマニュアルを作成していますか？ 数百人規模の大きな会社であれば専属のマニュアル作成チームがあるかもしれません。aptpodでも専属のチームがいてくれたら心強いのですが、絶賛成長中のスタートアップということもありまだ専属チームはありません。
そのような中でも、手塩にかけて開発したプロダクトを多くのユーザーに使っていただくためには、ユーザーマニュアルは欠かせません。我らaptpodのエンジニアが、エンジニアならではのアプローチでユーザーマニュアルを作った方法を紹介します。
自動でできるところは自動で！ バージョン管理でデグレなんてしない！ をモットーに💪
前段: aptpodでのプロダクト開発の進め方
ユーザーマニュアル作成の話に入る前に、aptpodでプロダクト開発をするときの進め方を紹介します。aptpodでは、ハードウェア・サーバー・インフラ・UI・デザインと、一つのプロダクトにさまざまなスキルを持ったメンバーがアサインされます。プロダクトの提供する技術的範囲が広いため、ユーザーマニュアルもそれぞれの領域の知識が必要になります。
そのような背景もあり、プロダクトの開発に関わった複数人が同時に、デグレが無く安全に、楽して、クオリティの高いユーザーマニュアルを作成することが求められました（aptpodではユーザーマニュアルも一つの製品として力を抜かない😎）。
エンジニアによるユーザーマニュアル作成の流れ
いよいよ本題に入ります。大まかには、仕様を把握しているエンジニアが文章やざっくりとした図版のイメージ（UIのキャプチャやパワポでちょっとお絵かきしたり）を作成し、そのデータを元にデザイナーがページレイアウトや図版を起こしていく流れになります。
下記が実際の作成フローです。
- 目次作成
- 担当者をアサイン
- 校正ツールの導入
- 文章作成
- GitLab上で相互レビュー
- レビュー後の文章をWord化
- PDF生成
各Stepでどのように進めたのか解説していきます。
1. 目次作成
全体の文章構成、ボリュームをつかむべく目次を作成します。最初から完璧な目次は作れないので、書いてる中でのアップデートする前提で大丈夫です。ここでは共同編集できるようにGoogle スプレッドシートで管理しました。
2. 担当者をアサイン
目次をまとめたGoogle スプレッドシートに 担当者 という項目を設け、章・節ごとにメインで実装していた開発者を担当者としてアサインしました。仕様に詳しい人が書いたほうが確実で手戻りも少なくなります。中には担当者がいない（開発とは直接関係のない）章も出てくるので、そこは私が担当しました。
3. 校正ツールの導入
人によって文章の書き方にばらつきが出てくる可能性があるため、下記の 校正ツール を導入します。校正ツールとは、文章を一定ルールに沿って自動で校正してくれるツールです。
テキスト校正くんはVisual Studio CodeにインストールするPluginです。JTF日本語標準スタイルガイドのルールに沿って校正してくれます。
自動でできるところは自動で！人で担保が難しいところはツールに任せちゃいましょう。
4. 文章作成
いよいよ文章を書き始めます！ 文章はエンジニアライクな Markdown で書き進めます。文章だけ書くのであれば通常のMarkdown記法のみでいいですが、文章の性質によっては強調して目を引くデザインにしたい部分もあり（取り扱いでの注意など）別途ルールを設けました。そのルールに沿って、後ほど説明する「6. レビュー後の文章をWord化」で自動変換します。
文章が書き上がったら、バージョン管理のためにGitLabへPushします。Gitで管理することによってデグレという最悪の事故を未然に防げることはもちろん、レビューの内容や編集の履歴を残すことによって、文章の修正意図を知れたり、その後の文章作成に役立てることができます。
GitLab上でのディレクトリ構成は下記のような構成にしました。Markdownファイルを節ごとに分けることで、各担当者間で作業が干渉しないようにしました。
バージョン管理でデグレなんてしない！マニュアル作成でバージョン管理しないなんて... もうそんな世界では生きられない...
5. GitLab上で相互レビュー
文章をPushできたら、レビュー担当者にレビューを依頼するために Merge Request を作成します。Pushされた文章をレビュー担当者が確認し、指摘ポイントはMerge Requestのコメントに記載していきます。文章作成者はその指摘を対応して再度Push、レビュー担当者が再度確認して問題なければ Approval（承認）とし、developブランチへマージできるようになります。
マージされたら、この節は作成完了です！！👏
6. レビュー後の文章をWord化
文章が一通り揃ったら、デザイナーへ文章とざっくりした図版を渡します。デザイナーの力は絶大ですね。ざっくり図版が、かっこよく、さらにわかりやすい状態に仕上げていただけました。
文章と図版が揃ったら、いよいよPDFへの書き出しのフローに入ります。今回は、出力後のページデザインを担保するために Markdownファイル → Wordファイル → PDFファイル という段階で書き出しました。
Markdownファイル → Wordファイル の変換は、Pandocで自動化しました。章ごとに分かれていたMarkdownファイルを一つに結合し、「4. 文章作成」で紹介したルールに沿ってデザインを反映させながらWordファイルが生成されます。
7. PDF生成
いよいよ最後の工程、 Wordファイル → PDFファイル です。生成されたWordファイルをWordで開き、PDF出力をポチ！ と、ここでアクシデント発生... 文章内で指定していたページ内リンクが切れちゃっていました...😱
macOSのWord特有の不具合のようで、macOSではなくWindowsのWordで開き、AcrobatからPDF出力することでページ内リンクも効いた状態のPDFが出力されました！！！
これにてユーザーマニュアル完成！！🎉
おわりに
最後にちょっとしたハプニングがありましたが、無事にエンジニアとデザイナーでユーザーマニュアルを作成することができました！ 自動化とGitを導入できたことで、デグレもなく、レビューもスムーズにでき、ユーザーマニュアルの中身に時間を割くことができました。
今回は私が代表で記事にしましたが、他にも関わったメンバーはたくさんいます。メンバー全員で試行錯誤しながら進めてきました。みなさん本当にお疲れさまでした！！！ 打ち上げしたい！！！ ｳｪｰｲ🍻
