学士論文を書き始めたばかりなので、適切な文書を作成する方法を尋ねたいと思います。
このプロジェクトの範囲には、マイクロコントローラーソフトウェア(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
これで十分ですか?目標を達成するために、それをさらに開発する必要がありますか?
ドキュメント構造には、客観的側面と主観的側面の両方があります。主観的な部分はここでは範囲外です。さらに、ドキュメントは方法論に大きく依存します。したがって、包括的な答えではなく、すべての客観性で考慮する必要がある一般的な問題のリストを提案します。
要件:選択肢ドキュメント/process
はおそらくあなたの製品とデザインの選択についてです。しかし、あなたの製品はどのようにその目的を果たしますか?そして、この目的は何ですか?
nodes
が個人データを記録する可能性がある場合はGDPR。これには設計によるプライバシーが必要です)。Integration:ただし、システムにはいくつかのコンポーネントがありますが、ここではnode
やcontrol_room
、コンポーネント間の統合という、目に見えない3つ目の試みが常にあります。
テストと品質:テストは、製品が機能し、要件を満たしていることを証明します。従来のプロジェクトの場合、承認プロセスにはテストが必要です。アジャイルアプローチを採用している場合、すべてのユーザーストーリーから、ある種のテストでカバーする必要があるいくつかの成功基準がわかります。 TDDを使用している場合は、テストの重要性についてはすでにご存じでしょう。
オペレーター/ユーザーマニュアル:そこには多くの素晴らしいプロジェクトがあり、それらはソースコードと設計決定の長い歴史に飛び込まない限り役に立たないものです。あなたがそこにいないときにそれを実行する必要がある人を考えてください。何をどこにインストールし、どのように実行するかについての最低限の説明が必要なようです。
さらに、未解決の問題のリストを維持することを考えましたか?つまりできるだけ早く答えるか、後で取り組む必要がある問題に取り組むときに、どんな種類の問題、質問、または考えがありますか?これは必須ではありませんが、個人的には、後で私たちに影響を与える可能性のある問題を見逃さないように私と私のチームを大いに助けました。
Christophe 上記は、IMHOに必要な追加の構造のほとんどを提供しています。 Githubプロジェクトを確認すると、ユーザーが慣れている一般的なフォルダー構造を提供するのに役立つことがわかりました。上記に加えて私のさまざまなConfluenceテンプレートから:
フォルダ(コメント)
Dev(開発用のフォルダ)–これは、/クリストフがこれまでに演算子を除いて説明したものです/ユーザーマニュアル–例以下のオペレーション
Ops(操作用フォルダ)
ハウツー記事
辞書