昨日、はてなアンテナのヘルプリニューアル版
http://hatenaantenna.g.hatena.ne.jp/
を公開しました。
これまで、ヘルプは各サービスの中にHTMLファイルとして用意し、上部のメニューからリンクをする形を取っていました。
HTMLファイルに各機能の説明を書くのですが、機能追加は変更を行う際にヘルプの更新が滞り、記述が実態に合わない問題が出てしまっています。
社内の業務フローを考えると、
- 機能追加を行う方針をミーティングで決め、担当者が開発を行う
- 動作、インターフェースなどのチェック
- 問題なければ本番環境に反映
- オフィシャルの日記で告知
- ヘルプに反映
という手順を踏むわけですが、4.までは行っても、5.が漏れてしまう場合がありました。この点は以前から多くのユーザーさんに指摘を頂いています。
オフィシャルの日記での告知はできるのに、ヘルプへの追記ができない理由の一つには、HTMLファイルの更新に手間がかかることが1つの原因でした。また、4.5.の作業を技術者が行っていたのですが、ヘルプを書くよりもついつい次の開発に手を動かしてしまう、ということもその理由でした。
こうした反省を踏まえて、スタッフの役割を見直すと同時に、はてなグループを使って分かりやすく、実態に合ったヘルプを目指したいと考えています。
ヘルプの構成
g:hatenaantennaグループを作成する中で、「ヘルプドキュメントはどのようなもので構成されるべきか」をまず考えました。
これは単に全ての機能を順番に書き連ねれば良い、というものではなくて、そもそもはてなアンテナって何なの?という方から、ロボットの拒否の仕方が知りたい、という具体的な目的のある方までが分かりやすく参照できる必要があります。
色々考えるうちに、以下の3つの要素が必要ではないかと考えるようになりました。
- はてなアンテナって何?→そもそもはてなアンテナで何ができるのか
- はてなアンテナの使い方→順番に読んでいくことで主な機能が使えるようになるチュートリアル的な説明
- はてなアンテナ機能一覧→全ての機能を網羅して仕様等を解説する
これらを互いにキーワードリンクで結びつけ、参照できるようにすることで色々な用途に耐え得るドキュメントにできないか、と考えました。
g:hatenaantennaはまだ全てのドキュメントが編集できておらず、製作途上の状態ですが、まずははてなアンテナのヘルプとしてこのドキュメントを完成させ(というより定常運用状態に持って行き)、その後各サービスのヘルプとして展開していきたいと考えています。
ご意見やご感想などがあれば、ぜひお寄せください。