私は保険会社で働いています。当社には、約 150 人の従業員と一部のプロバイダー (アウトソーシングやカスタムメイドのアプリがほとんど) で構成される独自の開発部門があります。私たちの会社では、私のチームが非機能ロジック ライブラリと呼んでいるものを作成しました。つまり、セキュリティ、Web サービス、ロギング、メッセージングなど、私たちの部門のすべての開発チームに共通することを処理するためのソフトウェア ライブラリです。ほとんどの、またはこれらのツールは、ゼロから作成されるか、デファクト スタンダードを採用したものです。たとえば、ロガーは Log4J に基づくアペンダーであり、ログ メッセージを DB に保存します。また、アプリケーションで使用するライブラリ (たとえば、Web サービスが使用するフレームワーク) も定義します。私たちは、組織全体でほとんど JavaEE と Oracle AS を使用しています (いくつかの Websphere アプリケーション サーバーを使用)。
これらのプロジェクトの多くは、アーキテクチャ (ユースケース、UML 図など) が文書化されており、通常、生成された文書が利用可能です。私たちが見たのは、私たちが提供するライブラリを使用するのが難しい場合があり、常に質問をしたり、単にそれらを使用していないということです。
そのため、彼らのために、よりわかりやすいドキュメントを作成する予定です。私の質問は次のとおりです。ソフトウェア ドキュメントに含める必要があるベスト プラクティスまたはチェックリストは何ですか?
何かが頭に浮かぶ：
- API リファレンス ガイド
- クイックスタートチュートリアル
- API 生成ドキュメント。
- 検索可能である必要があります
- Web アクセス
他に何が必要ですか？また、あなたの経験に基づいて、この種のドキュメントを維持 (最新の状態に保つ) および公開するための最良の方法は何ですか?