DevNet の Notes (注釈)機能が目指すもの

この記事は Qt DevNet Blog の "Doc Notes - We Have a Vision" を翻訳したものです。
執筆: Alexandra, 2012年3月22日

Qt のドキュメントを Qt Developer Network に移行するという話を始めた時、Marius は彼のイメージするものを説明する為に PHP のドキュメントを例に挙げました。そこには PHP グループによってたくさんの注釈が追加されたドキュメントがありました。これらの追加された内容が、いろんな意味でドキュメントとしての役割をもっていました。

背景

Qt のドキュメントがトップレベルであることは明らかですが、従来の静的なやり方ではとても大きなチャンスを逃すことになります。皆さんのように、たくさんの経験のあるプログラマーが毎日クラスドキュメントを見ています。Qt をさまざまな環境で試し、さまざまなことを実装し、たくさんのことを知っています。とっておきのソリューションや、ちょっとした裏技、お気に入りのユースケースなどをお持ちのことでしょう。

経験あるテクニカルライターが作るドキュメントは素晴らしいものですが、このクラスドキュメントに皆さんの注釈を加えることによって、さらに進化させることができるはずと考えました。

役に立つ注釈とは

そのページのクラスに関係のあることは全て注釈としてつけることができます。例えばクラスの使用目的や、使用例を説明するコード、そしてクラス実装の説明などが考えられます。よくある間違いを避けるヒントや賢い使い方なども良いでしょう。関連した wiki のチュートリアルやフォーラムのスレッドへのリンクがあると、そのクラスの背後にあるものを知りたい時や API の使い方を学習している時に便利かもしれません。

さらに、より詳細なサンプルコードがあれば実際にコンパイルして学習することができます。コードは純粋なドキュメントをより生きたものにし、クラスリファレンスよりも詳細な情報を与えてくれます。これらのサンプルは Qt を始めたばかりの人たちには大きな力となるでしょう。

PHP ドキュメントの例

では、アイデアの元となったものを見てみましょう。PHP ドキュメント の date 関数のページです。公式ドキュメントの部分は分かりやすく、十分に目的を果たしています。しかし PHP のユーザーはその関数にまつわる実用的な情報をさらに追加したいと感じました。

私は PHP のデベロッパーではありませんが(というか、デベロッパーではありません)、これがいかに便利かはすぐに分かります。注釈を検索すると私のような初心者でもすぐに重要な情報を見つけられるので、かなりの時間を節約できます。こういった情報は「公式な」ドキュメントには見つかりません。

12年間でどれだけの貴重なコンテンツが蓄積されたか、考えてみるとかなりすごいことです。もちろん、その全てが素晴らしい情報というわけには行きません。理想とは言いがたいものもあります。

というわけで、最も役に立つ注釈が最初に表示されるように、既存のコンテンツ向け評価システムを適用しました。サイトの他のコンテンツと同じように、高評価をつけることができますし、この機能に関しては、管理者に報告する意味で低評価をつけることもできます。

最後に

いかがですか？Notes 機能の役割について、Qt のドキュメントの方向性について理解の助けになれば幸いです。皆さんならドキュメントにどんな注釈をつけますか？いつものように、提案や改善案は大歓迎です。コメント欄にお書き下さい(訳注：元記事 へのコメントが確実です)。