やりたいこと
chm ファイル（Windows用のヘルプファイル）の代替です。
- WPF で作ったアプリのメニューとかからヘルプを表示できるようにしたい。
- ヘルプファイルをインストーラに同梱して配布したい。
- 配布用のドキュメントとして整ったフォーマットにしたい
- Markdown でメンテできるようにしたい。
製品は BtoB な業務アプリを想定しています。
最近だとこのような製品でも、ブラウザを起動してオンラインマニュアルへアクセスさせるものが多いと思います。しかしそうするにはサーバやドメインの準備も必要だったりするので、製品が軌道に乗って予算が降りてこないと厳しいです。要求次第では過去バージョンのメンテも続ける必要がありますし、アプリとのバージョンをそろえる手間も無視できません。
というところでオフラインなヘルプをサッと作りたいところですが、クライアントさんもキレイなアプリを見慣れてきている昨今、体裁はある程度整えたい要求が出てくることもよくあります。
さすがに生テキストファイルや Office 文書を表示するのはアレなので PDF や CHM あたりが候補になるのですが、PDF は大きくなると閲覧性悪くなるし、CHM は 古すぎて色々問題を抱えています。HTML ファイルだけ配布はアリかもしれませんが、ローカルで Webサーバ立てないと JavaScript を動かせないので検索などを十分にサポートできず、 PDF とあまり変わらないです。
作ったもの
MkDocs を使って Makdown から出力した HTML を、 NW.js の実行ファイルから起動できるようにしています。
出来上がった docs.exe を起動するだけで OK. 配布はこのフォルダを丸ごとコピーで。
上記リポジトリには最小構成が入っているので、色々なプロジェクトで使いまわせるはずです。
使い方は README.md をご覧ください。
中身について
Staticなサイトを NW.js で動かしているだけです。
Poetry
ヘルプを作業分担するときにツールのバージョンを合わせるため、Python(MkDocs関係) のパッケージ管理に Poetry を使っています。
MkDocs
material テーマと、検索の日本語対応を ON にしてあります。
NW.js
MkDocs の出力フォルダ (siteフォルダ) をエントリーポイントとして実行ファイルを出力するようにしてあります。
リポジトリの中に package.json が2つある点に注意です。
- /package.json
- NW.js を使ってアプリをビルドするための設定です。
- /docs/package.json
- NW.js によってビルドされるアプリの設定です。
mkdocs build時にsiteフォルダへコピーされます。
- NW.js によってビルドされるアプリの設定です。
おわりに
技術的には特に面白みもないんですけど、自分の仕事ではこのスタイルでヘルプを配布することが多くなってきたので、テンプレリポジトリを作ってみました。
それにしても、BtoBデスクトップアプリなみんなはヘルプどうしてるんだろう。
案外 PDF,CHM で足りているのか、移行先が無いから我慢して使ってるのか、特に体裁に関心がないのか。一時期ヘルプを作るプロプラソフトが販売されていたこともあった気がしますが、クローズしたぽいところを見るとヘルプに予算掛けるケースがそもそも少ないのでしょうか。バージョン問題とか運用チームと折衝する必要もあるから、結局のところ凝ったことしないのがベターなのかも？
各々のルールにも依りますが、可能ならこのシステムすら不要で、 GitHub Pages で十分だと思います。MkDocsはバージョンのスナップショット取ることもできるし。