2019の19日目担当、Webチームの蔵下です。数百人規模の大きな会社であれば専属のマニュアル作成チームがあるかもしれません。aptpodでも専属のチームがいてくれたら心強いのですが、絶賛成長中のスタートアップということもありまだ専属チームはありません。そのような中でも、手塩にかけて開発したプロダクトを多くのユーザーに使っていただくためには、ユーザーマニュアルは欠かせません。我らaptpodのエンジニアが、エンジニアならではのアプローチでユーザーマニュアルを作った方法を紹介します。aptpodでのプロダクト開発の進め方ユーザーマニュアル作成の話に入る前に、aptpodでプロダクト開発をするときの進め方を紹介します。aptpodでは、ハードウェア・サーバー・インフラ・UI・デザインと、一つのプロダクトにさまざまなスキルを持ったメンバーがアサインされます。プロダクトの提供する技術的範囲が広いため、ユーザーマニュアルもそれぞれの領域の知識が必要になります。そのような背景もあり、プロダクトの開発に関わった複数人が同時に、デグレが無く安全に、楽して、クオリティの高いユーザーマニュアルを作成することが求められました(aptpodではユーザーマニュアルも一つの製品として力を抜かない😎)。エンジニアによるユーザーマニュアル作成の流れいよいよ本題に入ります。大まかには、仕様を把握しているエンジニアが文章やざっくりとした図版のイメージ(UIのキャプチャやパワポでちょっとお絵かきしたり)を作成し、そのデータを元にデザイナーがページレイアウトや図版を起こしていく流れになります。各Stepでどのように進めたのか解説していきます。全体の文章構成、ボリュームをつかむべく目次を作成します。最初から完璧な目次は作れないので、書いてる中でのアップデートする前提で大丈夫です。スプレッドシートで管理しました。スプレッドシートのキャプチャです。いう項目を設け、章・節ごとにメインで実装していた開発者を担当者としてアサインしました。仕様に詳しい人が書いたほうが確実で手戻りも少なくなります。中には担当者がいない(開発とは直接関係のない)章も出てくるので、そこは私が担当しました。校正ツールとは、文章を一定ルールに沿って自動で校正してくれるツールです。CodeにインストールするPluginです。JTF日本語標準スタイルガイドのルールに沿って校正してくれます。自動でできるところは自動で!人で担保が難しいところはツールに任せちゃいましょう。文章だけ書くのであれば通常のMarkdown記法のみでいいですが、文章の性質によっては強調して目を引くデザインにしたい部分もあり(取り扱いでの注意など)別途ルールを設けました。レビュー後の文章をWord化」で自動変換します。追加したルールの一部。誰でも読めるようにQiitaTeamで管理しました。文章が書き上がったら、バージョン管理のためにGitLabへPushします。Gitで管理することによってデグレという最悪の事故を未然に防げることはもちろん、レビューの内容や編集の履歴を残すことによって、文章の修正意図を知れたり、その後の文章作成に役立てることができます。GitLab上でのディレクトリ構成は下記のような構成にしました。Markdownファイルを節ごとに分けることで、各担当者間で作業が干渉しないようにしました。GitLabでのディレクトリ構成。章ごとにディレクトリを分け、節ごとにMarkdownファイルを分けました。Requestのコメントに記載していきます。Approval(承認)とし、developブランチへマージできるようになります。指摘ポイントごとに管理できるのはよかった。文章が一通り揃ったら、デザイナーへ文章とざっくりした図版を渡します。デザイナーの力は絶大ですね。図版が、かっこよく、さらにわかりやすい状態に仕上げていただけました。文章と図版が揃ったら、いよいよPDFへの書き出しのフローに入ります。いう段階で書き出しました。変換は、Pandocで自動化しました。文章作成」で紹介したルールに沿ってデザインを反映させながらWordファイルが生成されます。サンプルMarkdownファイルをWordファイルへ変換した様子。自動化とGitを導入できたことで、デグレもなく、レビューもスムーズにでき、ユーザーマニュアルの中身に時間を割くことができました。今回は私が代表で記事にしましたが、他にも関わったメンバーはたくさんいます。メンバー全員で試行錯誤しながら進めてきました。25日目=最終日の記事です。本ブログへいらっしゃったみなさま、初めまして。aptpodという会社のQAチーム横田です。(1)月別アーカイブスターをつけました引用をストックしましたストック一覧を見る閉じる引用するにはまずログインしてくださいログイン閉じる引用をストックできませんでした。再度お試しください閉じる限定公開記事のため引用できません。