静的ジェネレータを使ってExcelマニュアルをWeb公開するアイデア

ちょっとしたExcelマニュアルの内容を公開する仕事があって、色々調べたこと、考えたことをラフなメモ書き。

【参考１・MkDocs】
MkDocs

ドキュメント作成ツール > MkDocs - Qiita

MkDocsでドキュメント管理 - notebook

ドキュメント生成ツール「MkDocs」でRedmine Guide日本語訳のWebサイトを作ってみた - ファーエンドテクノロジー株式会社

【参考２・Jekyll】
まだWordPressで消耗してるの？Netlify CMSでブログを作成しよう！ - Qiita

Jekyll ? シンプルで、ブログのような、静的サイト

Jekyllで作るシンプルWebサイト - Jekyllとはなにか | CodeGrid

GitHub Pages の Jekyll で Web サイトを無料公開する方法 - Qiita

【１】Excelマニュアルの問題点

IT業界では、設計書のたぐいは、とにかくExcelでマニュアルを作りたがる。
インストールマニュアル、製品マニュアル、運用マニュアルなど。

Excelマニュアルの一番の問題は、誰も見なくなることだ。
共有ファイルサーバーにExcelマニュアルを置いてメールで連絡しても、そこにたどり着いて、Officeファイルを開かなければ見れない。

マニュアルを作った本人としては、皆に周知して使ってもらいたいのに、いつも、どこにあるのですか？という問合せばかり受ける。
こういうExcelマニュアルのたぐいは、社内イントラ上で公開できればいいのに、といつも思っている。

また、社内ポータルにリンクを貼っておけば、検索エンジンや更新案内で、勝手に見てくれるようになる。
つまり、マニュアル設計者がプル戦略で周知できる仕組みを作ればいいはず。
すなわち、多数のユーザが自ら情報を引き出すような仕組みを作ればいい。
プロモーション戦略におけるプル戦略と考え方は同じ。

では、マニュアルをプル戦略で公開する仕組みはどう作ればいいか？

【２】静的ジェネレータの使い道

【２－１】マニュアルのようにドキュメントの構成が統一的で簡単であるならば、静的ジェネレータでHTMLを自動生成してApacheで公開するのが一番簡単だ。
静的ファイルを配置するだけでいい。

この発想に落ち着くまでに、CMSのような製品も必要か色々考えてみた。
しかし、複雑なドキュメントを書くのでなければ、静的ジェネレータでHTMLを生成するので十分。

たとえば、OSSのCMSならば、WordPressが一番有名だ。
ブラウザ上で更新できるし、管理画面や機能も豊富だ。

しかし、公開後のアプリ保守やインフラ保守を考えると、セキュリティパッチやVerUpのたびにWordPress本体の保守作業が発生して、かなり手間がかかる。
また、機能改善のためにプラグインを導入せざるを得ないが、WordPress本体のVerUpでプラグインの動作保証まで検証するコストも発生してしまう。
つまり、その後の保守コストが結構かかってしまう。

一方、静的ジェネレータであれば、普通は、Markdownでドキュメントを自然言語で書けるし、CSSやJavaScriptでプログラミング・ライクに装飾できるし、Gitのようなバージョン管理ツールと相性も良い。
Gitでバージョン管理できれば、ビルド管理やデプロイ管理も、今までの自分が持っているノウハウで自由にカスタマイズできるし運用しやすくなる。

ドキュメントの中身を保守更新することを考えると、コンテンツそのものはMarkdownでテキスト化してGitで管理して、いつでもビルド・デプロイできる環境を作っておいた方が良いと思った。

【２－２】では、お勧めの静的ジェネレータは何が良いのか？

単純なExcelマニュアルの元ネタは、Markdownやマインドマップで書いているので、個人的には、MkDocsで十分だった。

Pythonを入れて、インストール
pip install mkdocs
↓
MkDocプロジェクトを作り、Markdownでどんどんテキストに書いていく。
mkdocs new my-project
cd my-project
↓
書いたら、localhost上でプレビューしながらチェックする
mkdocs serve
↓
ビルドしてHTMLを生成したら、それをAacpheへアップして公開するだけ
mkdocs build

他の記事を探してみると、CMS代わりの静的ジェネレータは色々あるみたい。
個人的には、Ruby製のJekyllを触っていて、Blogコンテンツを移行できないかなあ、とか思っている。

Jekyllのメリットは、Blog記事をMarkdownで書き溜めておけば、GithubPagesでそのままWeb公開できる仕組みがあるからだ。
GitHubでバージョン管理して、静的HTMLをビルドしたら、GithubPagesへデプロイするような仕組みを作っておけばいい。

もちろん、静的ジェネレータは他にも色々ある。
大量のMarkdownドキュメントになってくると、もっと他の選択肢が必要になるのかな、と思う。

静的サイトジェネレーターは脱CMSなブログが作れるツール | Qookie Tech

WordPressの代わりになる！2018年注目の静的サイトジェネレーター6選｜ferret [フェレット]

静的サイトジェネレータを比較してみた - Qiita

【３】他の解決方法

【３－１】一昔前なら、PukiwikiのようなWikiで、こういうノウハウを書いて社内で共有するのが一般的だった。
最近はQiitaのように、技術ノウハウをWeb上で記述してストックし、公開して知見を共有するスタイルが流行しているように思う。

つまり、静的ジェネレータが最善の解決策ではない、とは思っている。

でも、製品マニュアルや技術ノウハウなど、不特定多数のユーザに情報共有したい内容をExcelマニュアルでまとめるのは、もう時代遅れではないか、と思う。
Qiitaにせよ静的ジェネレータにせよ、Web上で公開する仕組みが時代として要求されている、と感じる。

自分では大したことはない、と思う情報であっても、インターネット上あるいは社内イントラ上で公開されていれば、他の人が検索エンジンによっていつでも探し出すことができる。
つまり、検索しようとする人たちが、そのコンテンツに新たな価値を見出してくれるわけだ。

【３－２】Qiitaが静的ジェネレータよりも優れている点は、コメントやリンク、いいね、タグ機能など、著者と読者がインタラクティブにコミュニケーション出来る環境を提供している点だろう。
それによって、著者もフィードバックから得るものがあるし、他の記事と相互リンクすることで、記事の価値も高まる。
自分のアイデア、得られたノウハウは、一人で貯めておくよりも、Webで公開した方が、読者によって新たな価値を創りだしてくれるメリットがある。

【４】最近の自分のテーマは、Excelドキュメントをいかにテキスト化して、Gitのバージョン管理の配下に置けるようにできないか、だ。
それについては下記で色々考えていて、まだ試行錯誤中。

PlantUMLを使ってExcel設計書をテキスト化するアイデア: プログラマの思索

仕様書にもExcel脱却が求められている: プログラマの思索

今回の静的ジェネレータの件も、Excelマニュアルをいかに駆逐するか、という点で方向性は同じ。

プログラムだけでなく、設計書やマニュアル、ブログ、プレゼン資料のような自然言語で書くドキュメントも、Gitで構成管理できるようになれば、昨今の開発環境の技術革新の恩恵を受けられるはず。
このアイデアがどこまで実現可能で、どこまで問題や課題をクリアしてくれるのか、考え続けている。