プログラミング言語の文書化：リファレンスマニュアル
私たちは、製品ライン全体のドキュメントを刷新することを検討しています。その一部には、プログラミングマニュアルの一部として使用されるリファレンスマニュアルが含まれていますシステム。
プログラミング言語のリファレンスマニュアルを作成する場合、その言語の初心者が最大限に使用できるように、それを構成するための最良の方法は何ですか？
文書化された各キーワードの主要な側面は何ですか？
- 構文
- 説明
- 引数-該当する場合
- 戻り値-該当する場合
- 使用例は？
- 他に欠けているものはありますか？
コンセプト（ロック戦略、パフォーマンス関連の詳細など）もこのリファレンスマニュアルに記載する必要がありますか、それとも別のドキュメントですか？
これは外部消費用です。完全なドキュメントセットが既にあります（参照： http://www.rocketsoftware.com/u2/resources/technical-resources ）。私たちが何をすべきかを考え出す-私はすでに自分のアイデアを持っていますが、いつものように、私の意見だけに依存しないようにしています。
対象読者：当社のデータベースとツールを使用して、多くの業界でソフトウェアを作成する技術開発者。
対象読者のニーズに応じてドキュメントを整理します。
あなたの場合、主な対象者は明らかにソフトウェア開発者です。ここで考慮すべき部分は、このサブオーディエンスの異なる「サブオーディエンス」に対処することです。
- Hello World
すぐにその味を手に入れたい人は、サンプルアプリケーションをビルドして実行し、それがどのように見えるかを確認してください。
MySQLで演説されているような聴衆のことを考えてください "15 minutes rule" ：... MySQLのダウンロードが完了してから15分後にMySQLを起動して実行できるようにするユーザー。
- Fundamentals。
実用的なソフトウェアの作成を開始するために必要なことをすばやく学習したい人向け。 - 高度なトピック
すでに基本に精通し、実践されている開発者にとって、向こうに何があるかを知りたい。 Fundamentalsで取り上げられていない主流のトピック。 - スタイルガイド/推奨される方法
あなたが物事を行うことをお勧めする方法に興味がある人のための主観的なアドバイスとガイダンス。
質問は、これがあなたのケースで実質的な聴衆を持つ可能性があるかどうかを示していないので、考慮すべきオプションは、高度なトピックの一部/付録として含めるか、完全に削除することです。 - クイズ
聴衆のかなり限定された部分に関心があるかもしれない、メインストリーム以外のあいまいなトピック。たとえば、レガシーライン、またはアップグレード/移行/レガシーとの相互運用性などがある場合は、ここに入力します。特定の「エキゾチック」な環境で、ある機能に何らかの副作用がある場合、それはこの部分に入ります。
マニュアルの何かが疑わしい/あいまいな場合はどうなりますか？特定の概念の完全な説明がそのマニュアルを読みにくくすることがわかった場合はどうなりますか？マニュアルの特定のバージョンに誤りがあることが判明した場合はどうなりますか？
メンテナが考慮すべき2つの点は次のとおりです。
- 技術的/正式な仕様
マニュアルに疑わしい/あいまい/説明するのが難しいトピックがある場合は、仕様の特定の段落を参照して、それに関する厳密かつ明確な「公式」ステートメントを参照できます。言語構文の厳密で完全な（そしておそらく退屈な）記述は、そこに行く方がよいでしょう。
仕様の最重要事項は、読みやすさを犠牲にしても、技術的な正確さと完全性です。 - オンライン補足
URLを予約して、リリースするすべてのドキュメントの冒頭に配置するだけで、誰が読んだだけなのか疑問に思っている人たちが（代わりに）マニュアルのメンテナを困らせること）そして説明された間違いを見つけてください。Errata> Fundamentals> Release 2.2> Typo（28ページ）、2番目の文はluckで始まり、代わりにlockを読み取ります。
例えば。手動のメンテナーは、明らかに、同時実行性と完全な正確な記述の正式な仕様でのロックに興味があるでしょう-そこに置いてください。 FundamentalsまたはAdvanced topicsの読者は、仕様から抽出され、ニーズに合わせて調整された概要/概要/ガイドに興味があるかもしれません。
あなたのような他の言語のために提供されている参考資料の比較研究をアレンジすることは役に立つかもしれません。この研究は、以前にそれを行った人々が得た経験を活用し、彼らが犯した間違いを避ける方法を学ぶことを目的としています。
最後になりましたが、ソフトウェア開発と同様の方法でドキュメント開発をセットアップすることを検討してください。バージョン管理、定期的なリリース、問題の追跡、品質保証などのことを意味します。テクニカルライターがそのようなものにあまり慣れていないことが判明した場合でも、多少の妥協が必要になる場合があります。完璧な開発プロセスと「引き換えに」お粗末なコンテンツを取得したくないのでしょうか。
あなたがしなければならない最初のことは観客を評価することです。あなたの聴衆はLinuxカーネルハッカーですか、それともソフトウェアツールを使用して仕事をしているがソフトウェア自体には興味がなく、CSのバックグラウンドを持っていないハードウェアデザイナーですか？電気エンジニアは、const引数とnon-const引数の違い、オブジェクトへのポインタと参照などについて完全に明確でない可能性があります。プリミティブに名前がオーバーロードされている場合は、オーディエンスに適切なレベルでその概念を説明したほうがよいでしょう。彼らがC++プログラマであるなら、それは何でもないかもしれません。
評価する必要がある2番目のことは、言語のプリミティブの粒度です。粒度が細かいほど、各プリミティブの構文仕様の近くで使用例を提供する必要があります。つまり、コンテキストをインスタンス化する低レベルのプリミティブがあり、有用な処理を実行する前に3つの他の低レベルのプリミティブで操作する必要がある場合、いくつかの有用な関数の完全な例を用意することをお勧めします。マニュアルで。ほぼ使用できないドキュメントの優れた反例については、 online openssl ドキュメントを参照してください。
関数の副作用の説明を必ず含めてください。
いずれにしても、顧客のプログラマーが寝る前に毎晩あなたを呪いたくない場合は、いくつかの高レベルの関数プリミティブを実行するテスト済みのサンプルコードをたくさん含めてください。サンプルがコードのスニペットではなく、完全でコンパイル可能または実行可能な状態ですぐに使用できることを確認してください。
従来、技術ライターはリファレンスマニュアルとユーザーガイドを区別してきました。リファレンスマニュアルには、通常、構文の仕様、関数またはプリミティブのわかりやすい定義、落とし穴、パフォーマンスと副作用、および短い使用例の説明が含まれています。ユーザーガイドには、より拡張された使用例とより広範なエンジニアリング問題の議論が含まれています。カーニガンアンドリッチーの「Cプログラミング言語」は、この規則に対する優れた反例ですが、このアプローチは、文書化する言語が比較的単純な場合にのみ機能します。
著者は、1987年から1991年まで、Ready Systems Incの開発センターのエンジニアリングサービス部門のマネージャーで、5人の技術ライターのチームを管理する責任がありました。