マニュアルってどうしてます？

エンジニアの大島です。

マニュアル、システム作ってると避けられないですよね。

でも、ターゲット層によって形式は変わります。

シンプルなアプリなら、デザインでわかりやすくしつつ、Webのヘルプページ。

ソーシャルゲームなら、画面で誘導されるチュートリアル。

老若男女をターゲットにするなら、Webはもちろん、紙やPDFも考えねばなりません。

そして今回、PDFとWebの両方を作ることになりました。

でも、両方をメンテナンスしていくのは、更新の手間・コストが馬鹿にならないのでなんとか抑えたいところです。

そこで、目をつけたのがMarkdown。

普段、社内で共有するドキュメントでも使っており、学習コストがかからない。

MarkdownからPDFとWebの両方を出力できたら嬉しいなと思い調べました。

いろいろ試してみた結果、たどり着いたのがMkDocs。

Python製のドキュメントジェネレータです。

手順はこれくらいシンプル

$ pip install mkdocs
$ mkdocs new my-project
$ cd my-project
$ mv your-markdown.md docs/
$ mkdocs build

cssやjsを追加して見た目を調整することもできます。

もちろん、PDFとWebだと期待される見え方が違うので、内容や分量によっては難しいかもしれません。