問題タブ [documentation]

来月サポートグループに「引き渡す」必要があるアプリケーションを作成しました。

アプリケーションはかなり小さく(2 か月の開発)、2 つのクライアント側アプリケーションとデータベースで構成され、Windows プラットフォーム用に c# で記述されています。

サポート ドキュメントに何を含めるべきかについては大まかな考えがありますが、これまでのキャリアであまり多くのサポート ドキュメントを作成する必要がなかったため、含めるべき項目のしっかりとしたリストが必要です。

私の目標は、サポート グループの全員の生活を楽にし、できるだけストレスをなくすことだと思います。

だから私は私の質問は次のとおりだと思います：

1. サポート ドキュメントに絶対に含める必要があるもの

2. サポート ドキュメントをさらに便利にするために、サポート ドキュメントに追加したものは何ですか。

3. 私たちのすべての生活を楽にするために、引き渡し前に他にどのような活動を行うことができますか?

vb.net（vs2008）プロジェクトファイルをいじり始める必要があります。理想的には、その仕様への参照が必要です。

リンクは非常に役立ちます

perl ドキュメントで utf-8 文字を使用する必要があります。私が使用する場合：

変な文字が見えます。私が使用する場合：

すべて順調。

Ubuntu/Debian を使用しています。

Pod で特殊文字を使用する方法はありますか?

ドイツ語のウムラウト「Just a Test: äöüßÄÖ」を使用した小さな例を次に示します。

自分のコードにはコメントは必要ないと主張する同僚がいます。それは「自己文書化」です。

私は彼のコードをレビューしましたが、他の人が作成したコードよりも明確ではありますが、自己文書化コードがコメントや文書化されたコードと同様に完全で有用であることに同意しません。

彼の見解を理解するのを手伝ってください。

• 自己文書化コードとは
• 十分にコメントされ、文書化されたコードを本当に置き換えることができますか
• 十分に文書化され、コメントされたコードよりも優れている状況はありますか?
• コードがコメントなしで自己文書化できない例はありますか

多分それは私自身の制限に過ぎませんが、それがどのように良い習慣になるかわかりません。

これは議論を意図したものではありません - 十分にコメントされ、文書化されたコードが優先される理由を持ち出さないでください - これを示す多くのリソースがありますが、私の仲間には説得力がありません. そうではないと彼を納得させるには、彼の視点をもっと完全に理解する必要があると思います。必要に応じて新しい質問を開始しますが、ここで議論しないでください。

また、自己文書化コードに反対している人たち - これは主に、自己文書化コードの伝道者の視点 (つまり、肯定的な側面) を理解するのに役立つためです。

Visual Studio のビルド ステップで HTML ドキュメントを自動的にビルドするには、どのような手順を実行する必要がありますか? すべてのコメントが配置され、comments.xml ファイルが生成され、Sandcastle がインストールされました。ドキュメントを生成するために、ビルド後のステップに何を追加すればよいかを知る必要があります。

仕事上、外部企業の独自のデータベース ソリューションを処理するために、外部企業の API を使用してコーディングする必要があります。残念ながら、彼らが提供するドキュメントは、適切な API ドキュメントというよりもサンプル ガイドに近いものであるため、エラー コード、メソッドの戻り値、例外などの詳細については非常に簡単です。

たとえば、クラスには .GetErrorCode() メソッドがありますが、どの番号がどのエラーと一致するかを文書化していないため、これらのエラー番号が何を意味するのかわかりません。多くの場合、メソッドは Object を返しますが、実際に返される Object の型に関するドキュメントはありません。私は彼らに適切な文書化を繰り返し求めてきましたが、彼らは上記のような詳細は妥当性の秘密だと考えているようです. それで、限られた、または場合によっては存在しないドキュメントを回避できるツールまたは方法はありますか。

私は Visual Studo 2005 を使用し、.Net の下で C# でコーディングしていることに注意してください。

そして、誰かが「API を使用しないでください」と答える前に、私はそうしなければなりません。それは仕事のためです。

で設定できるすべての可能なオプションを見つけようとしていますweb.config。驚いたことに、これはまったく見つかりません。私はそれがMSDN内のどこかにあると思っていました。

技術的に「何でも」を追加できることはわかっていますweb.config。私が探しているのは、「出荷時」の.NETFrameworkが使用するものです。

特に今はこの<mailsettings>セクションに興味があります。
たとえば、私が見つけた多くの例で、それらが設定されていることに気づきましたDeliveryMethod="Network"。この属性が他にどのような値を取ることができるのか、私は本当に興味があります。

すべての属性とそのすべての値、およびそれらが持つすべての効果に関するドキュメントはありますか？

ここでのベスト プラクティスが何であるかはわかりませんが、特にスコープが小さい場合は、短縮された変数名をよく見かけます。したがって、(単純な Ruby の例を使用するために) の代わりにdef add_location(name, coordinates)、 のようなdef add_loc(name, coord)ものが表示されdef add_loc(n, x, y)ます。略語を見ることに慣れている人は、長い名前に疲れてしまうのではないかと思います。

冗長性は読みやすさに役立ちますか?それとも、すべての人の目を傷つけるだけですか?—人々は長い名前よりも略語や短縮された名前を好みますか?

リリースしたばかりの企業 Web サイトの更新について、コンテンツ編集者に引き渡す必要があります。どうやら、ノートを使ったトレーニング セッションでは十分ではありません。けっこうだ。

そのため、さらに恐ろしいドキュメントが迫っています。Google でかなり短いトロールを行った後、Web サイトまたは Web アプリケーションのハンドオーバーの基礎として使用する、適切で使用可能なテンプレートを見つけることができませんでした。そのようなドキュメントに表示されるべきであると私が見つけた最も有用なアイテムのリストは、Experts Exchange (敵) にありました。

1. システム概要・総論紹介
2. プロセスと部門間のプロセス フロー
3. システム構成、セットアップ、および依存関係
4. 技術的な要件、機能、制限
5. サポートプロセス
6. トラブルシューティングのための関係者のエスカレーション リストと連絡先情報

これは、作業を行うための優れた基礎です。サイトのコンテンツを変更するだけのユーザーのために「簡単に説明」できますが、クラウドで利用できる優れた標準テンプレートを知っている人はいますか? このリストに追加すべきものは他にありますか?

C++ で記述された COM SDK があり、製品のドキュメントを作成したいと考えています。ほとんどの人はおそらくこの COM コンポーネントとの統合に C++ を使用しないでしょうが、多くの人はそうするでしょう。

C++ 開発者が知る必要のある詳細を失うことなく、API を記述するのに最適な方法はどれですか。