web-dev-qa-db-ja.com

プロジェクトドキュメントの構成方法は？

学士論文を書き始めたばかりなので、適切な文書を作成する方法を尋ねたいと思います。

このプロジェクトの範囲には、マイクロコントローラーソフトウェア（node）とサーバーソフトウェア（control_room）。

すべてのプロジェクトドキュメントをソフトウェアリポジトリに配置したいと考えています。このようにして、すべての情報を1か所で見つけ、開発プロセスの選択を特定のコードにリンクできます。

現在、次のようになっています。

Folder                 Comment
----------------       -------------------
control_room/          source code for the server software
node/                  source code for the microcontroller software
docs/                  PROJECT DOCUMENTS (core topic of this question) 
README.md              small overview for the new readers

docs/プロジェクトドキュメントのフォルダは、ソフトウェアの作成方法を明確に示すことを目的としています。次のような構造になっています。

Sub-folder             Comment
----------------       -------------------
process/               All choices made during the project are reasoned here.
sprint_retrospectives/ Reflections on work done every 2 weeks.
supervisor_meetings/   Supervisor meeting minutes

これで十分ですか？目標を達成するために、それをさらに開発する必要がありますか？

agiledevelopment-processdocumentationproject
1
Mats Gausdal

ドキュメント構造には、客観的側面と主観的側面の両方があります。主観的な部分はここでは範囲外です。さらに、ドキュメントは方法論に大きく依存します。したがって、包括的な答えではなく、すべての客観性で考慮する必要がある一般的な問題のリストを提案します。

  • 要件：選択肢ドキュメント/processはおそらくあなたの製品とデザインの選択についてです。しかし、あなたの製品はどのようにその目的を果たしますか？そして、この目的は何ですか？

    • 目標と要件は、上司とのミーティングで必ず表示されます。他のいくつかは、あなたはチーム内で発見します。しかし、これでは不十分です。ユーザーと一緒に発見した要件についてはどうですか？または法的要件（例：nodesが個人データを記録する可能性がある場合はGDPR。これには設計によるプライバシーが必要です）。
    • スプリントについて言及しているので、ほとんどの要件は ser-stories または se-case 2.0 slices になります。工業製品を作る場合、プロジェクトの最後でもこれらすべてを追跡することは理にかなっています。

  • Integration：ただし、システムにはいくつかのコンポーネントがありますが、ここではnodeやcontrol_room、コンポーネント間の統合という、目に見えない3つ目の試みが常にあります。

    • 両方のコンポーネントがどのように組み合わされることになっていると思いますか？
    • テストはどこに置きますか？各コンポーネントの構造にいくつかの単体テストがあると想像できます。しかし、両方のコンポーネントが本当にうまく連携することを保証する統合テストはどこにありますか？

  • テストと品質：テストは、製品が機能し、要件を満たしていることを証明します。従来のプロジェクトの場合、承認プロセスにはテストが必要です。アジャイルアプローチを採用している場合、すべてのユーザーストーリーから、ある種のテストでカバーする必要があるいくつかの成功基準がわかります。 TDDを使用している場合は、テストの重要性についてはすでにご存じでしょう。

  • オペレーター/ユーザーマニュアル：そこには多くの素晴らしいプロジェクトがあり、それらはソースコードと設計決定の長い歴史に飛び込まない限り役に立たないものです。あなたがそこにいないときにそれを実行する必要がある人を考えてください。何をどこにインストールし、どのように実行するかについての最低限の説明が必要なようです。

さらに、未解決の問題のリストを維持することを考えましたか？つまりできるだけ早く答えるか、後で取り組む必要がある問題に取り組むときに、どんな種類の問題、質問、または考えがありますか？これは必須ではありませんが、個人的には、後で私たちに影響を与える可能性のある問題を見逃さないように私と私のチームを大いに助けました。

2
Christophe

Christophe 上記は、IMHOに必要な追加の構造のほとんどを提供しています。 Githubプロジェクトを確認すると、ユーザーが慣れている一般的なフォルダー構造を提供するのに役立つことがわかりました。上記に加えて私のさまざまなConfluenceテンプレートから：

フォルダ（コメント）

Dev（開発用のフォルダ）–これは、/クリストフがこれまでに演算子を除いて説明したものです/ユーザーマニュアル–例以下のオペレーション

  • アーキテクチャー（-アーキテクチャー–機能的要件ではないが、自明ではない）
  • 名前の基準
  • Bitbucket/GitHubから本番環境まで、プログラミングフレームワーク/言語ごと
  • サーバー/コントローラーのビルド用の中央ビルドサーバー（-存在する場合）

Ops（操作用フォルダ）

  • サーバープラットフォームのプロビジョニング（-使用するすべてのopsツール/ swには、それぞれ独自のフォルダーが必要です）
  • CI/CDパイプラインのインストール（-もしあれば）
  • 本番環境のサーバー/コントローラーの世代/バージョン
  • セキュリティ（設計および製造中）（-例：証明書、トークン、暗号化、パスワード）
  • 業務管理
  • トラブルシューティング
  • ロギング
  • モニタリング
  • パフォーマンス
  • リモート管理

ハウツー記事

辞書

1
AlexanderHedlund