プログラミング言語の文書化：リファレンスマニュアル

私たちは、製品ライン全体でドキュメントの改訂を検討しています。その一部は、リファレンスマニュアルのためのプログラミング言語システムの一部として使用します。

プログラミング言語のリファレンスマニュアルを作成する場合、その言語を初めて使用する人に最大限の使いやすさを提供するための最良の方法は何ですか？

文書化された各キーワードの重要な側面は何ですか？

• 構文
• 説明
• 引数-該当する場合
• 戻り値-該当する場合
• 使用例？
• 私が行方不明になっている他の人はいますか？

コンセプト（ロック戦略、パフォーマンス関連の詳細など）もこのリファレンスマニュアルに記載する必要がありますか、それとも別のドキュメントですか？

_{これは外部消費用です。すでに完全なドキュメントセットがあります（http://www.rocketsoftware.com/u2/resources/technical-resourcesを参照）。私たちが何をすべきかを解決する-私はすでに私のアイデアを持っていますが、いつものように、私は自分の意見だけに頼らないようにします。}

_{対象者：多くの業界でソフトウェアを生産するためにデータベースとツールを使用する技術開発者。}

対象読者のニーズに応じてドキュメントを整理します。

あなたの場合、主な対象者は明らかにソフトウェア開発者です。ここで考慮すべき部分は、この1つの異なる「サブオーディエンス」に対処することです。

1. こんにちは世界。
   すぐにその味を手に入れたいと思っている人は、サンプルアプリケーションをビルドして実行するだけで、その外観を確認できます。
   観客は、MySQLの「15分ルール」で取り上げられているようなものだと考えてください。
   

   _{...ユーザーがMySQLのダウンロードを完了してから15分後にMySQLを稼働できるようにします。}

2. 基礎。
   実用的なソフトウェアの作成を開始するのに必要なことをすぐに学ぼうとする人のために。
3. 高度なトピック。
   すでに基礎に精通し、実践している開発者にとって、そこに何があるかを知りたい。基礎で説明されていない主流のトピック。
4. スタイルガイド/推奨されるプラクティス。
   あなたが物事を行うことをお勧めする方法に興味がある人のための主観的なアドバイスとガイダンス。
   _{質問は、これがあなたのケースでかなりの聴衆を持つ可能性があるかどうかを示していないので、考慮すべきオプションは、それを高度なトピックの一部/付録として含めるか、完全に削除することです。}
5. 癖。
   主流以外のあいまいなトピックは、視聴者のかなり限られた部分に興味があるかもしれません。たとえば、レガシーラインがある場合、またはアップグレード/移行/レガシーとの相互運用性などがある場合は、ここに配置します。特定の「エキゾチックな」環境で一部の機能に何らかの副作用がある場合は、この部分に入ります。

^{マニュアル内の何かが疑わしい/曖昧な場合はどうなりますか？特定の概念を徹底的に説明すると、そのマニュアルが読みにくくなることが判明したらどうなるでしょうか？マニュアルの特定のバージョンに間違いがあることが判明した場合はどうなりますか？}

メンテナーにとって考慮すべき2つのことは次のとおりです。

1. 技術的/正式な仕様。
   マニュアルに疑わしい/曖昧な/説明するのが難しいトピックがある場合はいつでも、読者はそれに関する厳密で明確な「公式」声明のために仕様の特定の段落を参照することができます。言語構文の厳密で完全な（そしておそらく退屈な）記述はそこに行く方が良いでしょう。仕様の
   最大の考慮事項は、読みやすさが犠牲になったとしても、技術的な正確さと完全性です。
2. オンライン補足。
   いくつかのURLを予約して、リリースするすべてのドキュメントの先頭に配置するだけです。そうすれば、（手動のメンテナーを悩ませるのではなく）読んだばかりの地獄がどこにあるのか気になる人は、説明された間違いを見つけることができます。

   _{正誤表>基礎>リリース2.2> Typoページ28、2番目の文はluckで始まり、代わりに読み取りロック。}

例えば、手動のメンテナーは、明らかに、並行性の完全で正確な記述と正式な仕様のロックに興味があるでしょう-それをそこに置きます。基本または高度なトピックの読者は、仕様から抽出され、ニーズに合わせて調整された概要/紹介/ガイドに興味があるかもしれません。

_{あなたのような他の言語のために提供された参照ドキュメントの比較研究を手配することは役に立つかもしれません。この研究の目的は、以前にそれをやった人が得た経験を活用し、彼らが犯した間違いを避ける方法を学ぶことです。}

_{最後になりましたが、ソフトウェア開発と同様の方法でドキュメント開発をセットアップすることを検討してください。バージョン管理、定期リリース、問題追跡、品質保証などのことを意味します。テクニカルライターがそのようなものに実際に慣れていないことが判明した場合でも、妥協することをお勧めします。完璧な開発プロセスのために、安っぽいコンテンツを「引き換えに」取得したくありませんか？}

最初に行う必要があるのは、視聴者を評価することです。対象読者はLinuxカーネルハッカーですか、それともソフトウェアツールを使用して仕事をしているがソフトウェア自体には興味がなく、CSのバックグラウンドを持っていないハードウェアデザイナーですか。電気技術者は、constとnon-const引数の違い、オブジェクトと参照のポインタなどの違いについて完全に明確ではない可能性があります。 C ++プログラマーの場合は何でもないかもしれません。

2番目に評価する必要があるのは、言語のプリミティブの粒度です。粒度が細かいほど、各プリミティブの構文仕様に近い使用例を提供する必要があります。つまり、何らかのコンテキストをインスタンス化する低レベルのプリミティブがあり、有用な操作を行う前に他の3つの低レベルのプリミティブを操作する必要がある場合、有用な関数の完全な例があります。マニュアルで。ほとんど使用できないドキュメントの優れた反例については、オンラインのopensslドキュメントを参照してください。

関数の副作用の説明を必ず含めてください。

いずれにせよ、顧客のプログラマーが就寝前に毎晩あなたをcur倒したくない場合は、いくつかの高レベルの機能プリミティブを実行するテスト済みのサンプルコードをたくさん含めてください。サンプルがコードのスニペットだけでなく、完全でコンパイル可能または実行可能な状態であることを確認してください。

従来、技術ライターはリファレンスマニュアルとユーザーガイドを区別してきました。通常、リファレンスマニュアルには、構文仕様、関数またはプリミティブのわかりやすい定義、落とし穴の説明、パフォーマンスと副作用、および短い使用例が含まれています。ユーザーガイドには、より広範な使用例と、より広範なエンジニアリングの問題に関する説明が含まれています。KerniganとRitchieの「Cプログラミング言語」は、この規則に対する優れた反例ですが、このアプローチは、文書化する言語が比較的単純な場合にのみ機能します。

著者は、1987年から1991年までReady Systems Incの開発センターのエンジニアリングサービス部門のマネージャーであり、5人の技術ライターのチームを管理する責任がありました。