製品マニュアルの制作に開発手法を取り入れた話

Aptpod Advent Calendar 2018 23日目の記事です。
CTO の梶田です。

2回目は、エモい話にしようか迷ったのですが、
ぱっと書けそうになかったので
製品マニュアルの制作に開発手法を取り入れた話を

背景

弊社のビジネスとして
B2B向けで製品を開発しているのですが、
マニュアルって必要ですよね。

弊社もよくある形で
Wordで作ってpdfで提供する
という形であったのですが、
製品も増えるし、Word辛い（※ディスっているわけではありません）
エンジニアとしては使い慣れた形でできたらやりやすいのでは。。。
と思ったわけで
できればWebサイトでやりたい
ということで以下の要件を決め、模索をはじめました。

要件

• バージョン管理したい
• リリースノート系もまとめたい
• PDFで出力できる
• Webでも(html)
• 複数人で進められる
• 検索、メニュー
• 学習コスト高くない

導入

ドキュメント関連のツールをピックアップして -> #参考 候補
試したりしてみたのですが、
要件を満たすものとして
リリースして間もないFacebookがリリースしたドキュメント管理ツールDocusaurus
を使ってみることにしました。

ルールとしてはこんな形

＜ルール＞
- Wordからの解放！
- マークダウンで統一
- Gitで管理できる
- Git Flowで
- GitLabのDocs Groupに1アプリ1Project(リポジトリ)を作る
- [Docusaurus](https://docusaurus.io/) を使ってサイトを構成する
	- マークダウンで書ける
	- カスタムcss
	- 検索できる
	- 翻訳(日/英)
	- バージョンニング 
- マークダウン->PDF化:デザインテンプレートでできること
- 画像命名規則決める
- ファイルはセクション単位で分ける、なるべく小さくする
- 1アプリ1サイト
- バージョン付ける
- カスタマイズはブランチ切る（仮）
- 校正は自動化する（textlint）
- リリースノートはできるだけ自動化（仮）

実際

当初は、実際マニュアル書くメンバーも開発エンジニア寄りではなかったので
Gitや開発フロー(Git flow)をあまりやってない感ではありました。
1年ぐらい経ちますが、少しづつ慣れた感もあり、対象製品も増えてます。
WebサイトもPDFも同時にできたわけで前よりはよくなっていると思います。

まだまだ残件やこうしたいってことはありますが。。（汗

今後も試行錯誤しながらよいものを作っていければと思っています！

基本コンテンツ構成

基本構成はこんな形で

- TOP
	- 概要
	- 使い方
	- 特長
- GetStarted
	- チュートリアル
		- 動画
	- ガイドライン
- Docs
	- 詳細マニュアル
	- PDF化意識する
- Help
	- ヘルプコンテンツ 
- Blog
	- リリースノート	

• 実際の画面(Webサイト)

• PDFサンプル
  • 表紙サンプル:※PDF出力する際に表紙と目次を付ける

Tips

Tipsをいくつか

Project 基本構成

project
  ├─ docs : ドキュメント用のマークダウンファイル置き場
  |　　　　　　　　├─ assets  : マークダウン向けの画像ファイル置き場
  | 　　　　　　├─ xxxx.md :　　ドキュメントマークダウンファイル(※フラットに置く/ファイル名は命名規則に従う)
  | 　　　　　　├─ ...
  ├─ README.md : Project全体のREADME
  ├─ package.json : npm向けのパッケージ管理ファイル
  ├─ .textlintrc : textlint向け設定
  ├─ prh.yaml : カスタム辞書
  └─ website : ドキュメントのwebsite本体

npm scripts

• いくつか便利になるよう用意しておく

Run the Server

• localhost:3000 でサーバを起動
• http://localhost:3000 でアクセス可能

$ npm run start:docs

Check textlint docs

• docs配下とREADME.mdの校正チェックをする

$ npm run lint:docs

Check textlint docs add fix option

• docs配下とREADME.mdの校正チェックをする:fixオプション=自動修正

$ npm run lint:docs:fix

Build Static Pages

• ビルドする: website/build フォルダに静的ファイルが生成される

$ npm run build:docs

Vesioning docs

• Versionで固める: website/versioned_docs , versioned_sidebars フォルダに対象バージョンファイルが生成される
• コマンドの末尾に -- を書き、空白に続けて対象バージョンを記載する

$ npm run version:docs -- {バージョン番号(X.X.X)}

Output document PDF file

• ドキュメント向けのPDFファイルを出力する: dist フォルダにPDFファイルが生成される

$ npm run out:pdf

校正

• 表記揺れとか防ぐために校正は自動で textlintを使う
  • Atom/ Visual Studio Codeのプラグインあるので入れる

その他

• マークダウンで改ページする場合は、 <div style="page-break-before:always"></div> を入れる

参考

• Docusaurusの参考記事
  • (OSS向け)ドキュメントツールDocusaurus

候補

• API Doc寄りなのが多いのとデザイン入れるのが条件だったのでカスタムCSSでやれそうなのと上記参考記事+実際使っているユーザー事例があったため、 Docusaurus を採用

• Sphinx

  • API Doc寄りな感が強い、ぱっと書くのはよさそう
  • http://www.sphinx-doc.org/ja/stable/

• GitBook

  • よく見るがデザイン入れるの苦労しそう
  • https://www.gitbook.com/

• Slate

  • 情報あまりなかった / シンプルにやるにはよさそう / jsでテーマが敷居が高そう
  • https://github.com/lord/slate

• Docute

  • こっちも情報あまりなかった / シンプルにやるにはよさそう
  • https://docute.org/#/

• Docsify

  • 構築とか楽そう
  • https://docsify.js.org/#/