#3 LGM : About Documentation

この記事は、私がME310/Sugar2021-2022プログラムに参加して、学んだこと、感じたこと、考えをドキュメンテーション化していくものです。

#3 LGM

#3 LGMではME310/SugarプロジェクトにおけるDocumentationについてのレクチャーを受けました。

Documentationとは

Documentationとは、進めているプロジェクトについて常に記録してデータ化し、最終的に文書としてまとめ、第三者がそれを読んだ時にプロジェクトの進行や結果、今後についてわかるようにするものです。

この私のnoteも一種のDocumentationであり、プロジェクトが終わった後でも私自身がこれらの記事を見て振り返りを行うことができるようにしています。

ME310/Sugarプロジェクトは、企業と教育機関が提携する産学連携プロジェクトです。

企業はテーマと資金を提供し、学生たちはそれらを基にプロジェクトを進めていきます。そのため学生たちは企業へと、その進捗や結果、そして次にそのプロジェクトを進める際への提案、必要な情報をまとめ提示する必要があります。

これらの理由からME310/SugarプロジェクトではDocumentationが求められていますが、実はこれは企業内部でも必要なものでもあります。このプロジェクトを通じてしっかりとDocumentationのやり方、コツ、そして習慣をつけていきたいと思います。

Documentationのポイント

“Capture not only the design but the intelligence/essence of the design”

Documentationの構造は以下の通りになっています。

Front Matter
What is the context for your project and team?
What are the requirements behind your design?
What was your design development approach - what alternatives did you consider, how did you evaluate them?
What are the specifications of your design?
How did you manage your project?
What recommendations do you have for going forward?
Appendix

それぞれのフェーズにおけるポイントについては以下の通りです。
この中でも2つ目のRequirementsは、とても重要でありながら定義することは難しいため、最後に説明します。

Front Matter

Title Page - People do judge by the cover of the book
Executive Summary - Most people only read this
Table of Contents - For easy referencing
List of Figures/Tables - For easy referencing
Glossary - There is a tendency to create new terms

Context

What is the background of your project and team?

Problem Statement - Where did you start?
Need Statement - What needs did you uncover?
The Design Team - Who worked on the project?
Corporate Sponsor - Who requested the project?

Design Development

How did you go from problem to idea to reality?

The best way of telling your design story is often not chronological.

Specifications

Everything you need to know to recreate your design/prototypes

_Use Diagrams and lots of it
_Be very Specific
_Picture is worth a thousand words

Project Management

How did you plan and execute your project?

Gantt Chart fits well here.
Project Budget should also be included here.
Do talk about the Global Collaboration.
Personal Reflections are optional but always welcome.

Future Recommendation

What do you suggest in taking this project further?

Appendix

Source Code for Projects
CAD blueprints
Vendor Contact information
Presentations, brochures, and other project-related material
CDs(USB Sticks now) are more than welcome

Requirements

“If you really understand your design, you should be able to specify its requirements.”

プロジェクトの初めから全てのRequirementsが分かる訳ではありません。プロジェクトを進めていくうちに、Requirementsを発見していき、それらに対処していくことが必要となってきます。

Requirements are specific to your team, to your design.

Requirementは以下の様に記述することが好まれます。

Requirement | Rationale
- Sub-requirement 1 | Metric | Rationale
- Sub-requirement 2 | Metric | Rationale
...

以上これらに沿ってME310/Sugarプロジェクトでは、Documentationを行なっていきます。

まずは現在進めているSugarGameでDocumentationを作り、練習したいと思います。

次回は#4 SGM : Critical Function Prototypeです。

ーー

この記事はプロジェクト内のLecture資料をもとに作成しております。
無断転用などはおやめ下さい、よろしくお願いします。

All rights of contents and images reserve @SushiSuzuki