背景

弊社のビジネスとして
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/#/