ソフトウェア環境ドキュメントのチェックリスト [終了]

Question

私は保険会社で働いています。当社には、約 150 名といくつかのプロバイダー (アウトソーシングとカスタムメイドのアプリがほとんど) で構成される独自の開発部門があります。私たちの会社では、私のチームが非関数型ロジック ライブラリと呼ぶものを作成しました。つまり、部門内のすべての開発チームに水平的なものを処理するためのソフトウェア ライブラリです。セキュリティ、Webサービス、ロギング、メッセージングなど。ほとんどのツールまたはこれらのツールは、最初から作成されるか、事実上の標準を適応させて作成されます。たとえば、私たちのロガーは Log4J に基づいたアペンダーであり、ログ メッセージを DB に保存します。また、アプリケーションでどのライブラリを使用するか (Web サービスにどのフレームワークを使用するかなど) も定義します。私たちはすべての組織で JavaEE と Oracle AS をほとんど使用しています (いくつかの Websphere アプリケーション サーバーも使用しています)。

これらのプロジェクトの多くはアーキテクチャが文書化されており (ユース ケース、UML 図など)、通常は生成されたドキュメントが利用可能です。ここで私たちが目にしたのは、ユーザーにとって、私たちが提供するライブラリを使用するのが難しい場合があり、常に質問されたり、単にそれらを使用しなかったりするということです。

そこで、私たちは彼らのために、よりわかりやすいドキュメントを作成することを計画しているので、私の質問は次のとおりです。ソフトウェアのドキュメントに含めるべきベスト プラクティスまたはチェックリストは何ですか?

何かが頭に浮かびます。

1. APIリファレンスガイド
2. クイックスタートチュートリアル
3. API で生成されたドキュメント。
4. 検索可能である必要があります
5. ウェブアクセス

他に何があればいいでしょうか？また、あなたの経験に基づいて、この種のドキュメントを維持し (最新の状態に保ち)、公開する最善の方法は何ですか?

Answer 1

あまりにもバージョン管理であなたのマニュアルを参照してください。

ユーザーから読んでいたところ、あなたが知っているので、それはバージョン番号を持つすべてのページで確認してください。

CIサーバは行く取得や更新の際にLIVEドキュメントサイトにドキュメントをプッシュします。

あなたのようなドキュメントのクチコミレビューをコーディングしてください。

犬フードそれ：）

優し、

ダン