Engineering Notebook A Mentor’s Perspective Thomas Roell July 20-21, 2017

Why a Engineering Notebook ? There are a lot of well meaning rationales The students run their own startup Documentation is required for projects Part of your job later on in life In reality that does not motivate students Without motivation there is no product

What motivates students ? The EN is 30% of the BEST Awards The EN is 66% of the engineering department contribution The BEST Awards are a major part which decides if your teams goes to regionals The EN score is the criteria for the “wildcard” match

Anatomy of the EN, part I Up to 32 single-sided pages of primary content Up to 20 double-sided sheets of appendices (so 40 pages) Title page Table of contents Delivered as PDF (still true for this year?) Deadline is “Practice Day”, week 5

Anatomy of the EN, part II 3 main content rubrics (30 total points) Research Paper (4) Design Process (17) Quality (9) There is a score sheet as benchmark Doesn’t sound so tricky …

Where’s the catch ? There are only 5 weeks Most of your engineering team will be busy in week 5 and 6 Engineers do not like to write documentation

Drilling down some more The Research Paper is self contained There are some “checkoff” items that do not require a lot of effort Safety section Appendices Organization chart Engineering drawings Meeting Minutes Test Results

Research Paper 2 to 5 pages Needs to show how game relates to topic Needs to show how game relates to state or region “bESTology” is a good resource for ideas A lot of prepwork can be done before Kickoff Not on the critical path, but somebody needs to own it.

Design Process, part I Collection of subtopics: Implementation of the Engineering Design Process Brainstorming approaches Evaluation of design alternatives Offensive and defensive evaluation Software Design and Simulation Safety Support Documentation (appendices)

Design Process, part II Lot’s of challenges for you as mentor The first few team meetings need to be planned around documentable items Analysis of the game Coming up with a goal (how many points can we get) How to get there (iterative approach, throwing out ideas ?) Do we leave anything on the table (alternatives ?) Risk / Reward analysis Pictures of whiteboards help a lot Have students take notes

Design Process, part III A team structure is needed early on to assign responsibilities Notes and pictures only work if students understand why they are needed Go through the notes as a group at the end of a meeting to make sure they are complete (5 mins) Provide a space where documents can be shared (Google Drive or such)

Design Process, part IV Schedule is king – the robot is the critical path Some content will arrive last minute Defensive evaluation will happen a lot when there is a robot to play with What do we do if XYZ breaks ? What do we do if the robot gets stuck ? What do we do if our robot gets blocked ? What can go wrong ? Do we have a checklist ?

Overall Quality Peer review on completed sections Somebody needs to be in charge Editor Does not provide content Cracks the whip on team members to provide assigned content Edits (read: rewrites lousy language) Formats the document with a consistent look and feel Peer review on completed sections Let students score they our work “What would it take to get to the full score ?”

Where does the mentor fit in ? Schedule is king – time management Provide samples Sample Engineering Notebooks Sample organization charts Sample research papers Samples for acceptable language Provide feedback, but do NOT write content for the students Set expectations, goals

Team Organization Engineering department Software Design (Drawings & CAD) Build … Each group naturally supplies content Build group would provide the Safety section Not every group is busy at all stages, hence idle time can be used to schedule documentation

Engineering Design Process Strategy drives requirement definition We need an arm The arm needs to reach 42 inches It needs to lift 3.14 lbs Requirements drive preliminary prototype We use CAD to have a early visualization Prototype drives detailed design We use CAD to design the parts Assembled CAD model as handoff criterium Detailed design drives handoff criteria to software and manufacturing

Engineering Design Process Detailed design drives requirements documents Software Manufacturing Detailed design results in a set of drawings Software and Manufacturing need to come up with a test and integration plan It gets hectic the night before practice day If you know how to test it, you understood the probem All of those stage feed directly into the EN Requirements / integration / test documents go into appendix Process description goes into EDP section Pictures, sketches, whiteboards, cardboard models …

Brainstorming Approaches I do not like this section at all, I do not like the name It’s really about how the team develops ideas What’s the formalism Everybody can contribute Vote, guess ? What constitutes progress We as a team have a HUGE problem with that Somebody comes up with the first approach The approach gets improved upon or it’s shot down (rarely) No idea has an owner, it’s either good or bad We vote what Pizza, but an approach is either good or bad So we go directly to the analytical evaluation

Analytical Evaluation and Design Alternatives This overlaps with the first stage of the EDP Strategy has been selected and needs to be implemented What are the requirements ? What are the constraints ? Are there alternatives ? Are they likely better ? Are they more risky ? Are they simpler or more complex ? This is where the math part goes Dimensions (bounding box, center of gravity) Torque required Lift capability required Gear ratios Small wheels vs. large wheels

Offensive Evaluation This is your teams strategy Include some math to predict the point outcome How efficiently can driver get the points What are the tradeoffs between items Points vs. Time Risk vs. Benefit Skill required Estimate a point ceiling (absolute and relative) Identify critical paths (A needs to happen before B)

Defensive Evaluation Can another team mess with your strategy ? Actually seen this in regionals Your team needs to think about a plan B What can go wrong outside you control ? Game pieces in the way Effects on your design ? Robot fails Catastrophic failures What are the parts of the Robot that are critical Much of this will happen AFTER “Practice Day”

Software Design and Simulation Do NOT use EasyC (we got burned) RobotC seems to be solve a lot of problems with documentation Source Core can be exported and put under version control Algorithms can be developed offline in C / C++ Algorithms can be simulated offline in C / C++ or even Python Define a requirements document Button mapping on the controller Port mapping on the Cortex Test / integration plan

Software Design and Simulation Good code is self documenting Button mapping needs to be a comment in the code Port mapping needs to be a comment in the code The code needs to be in the appendix There NEEDS to be version control of some sort Often a new feature is a step back The process needs to be documented As simple as attaching a data and sequence number to the source file Perhaps using github ?

Software Design and Simulation There are lot’s of problems with that section EasyC / RobotC have no simulation mode You cannot just hook up the controller and simulate input/output Only Simulink allows for that … Unit tests are possible (test a single component) But the robot is not ready yet when software is written EasyC / RobotC have no record/replay mechanism There is no physical model simulation (torque response curve of a motor) So at the end of the day in this section you will need to give up points Perhaps other mentor have better ideas there …

Document Structure Judges will judge by section Judges may not see all your appendices There is no good reason to lose points because content was not seen by a judge Identify in your TOC where the big ticket items are Keep source references with your research paper, not in the appendix Describe in your content what is in the appendix and reference it, but leave the gory detail in the appendix

Document Structure There are simple checkoff items that need to be there Spacing Margins Page numbers Title Page and TOC Picture labels Table labels The editor needs to be in charge of those The Engineering Notebook is a whole team effort Needs tools to allow parallel editing Needs some form of versioning to avoid lost edits

Scheduling The Engineering Notebook has to be handed over on “Practice Day” (was it noon ?) There is no good reason to be early Use every minute on “Practice Day” to check and improve the document Upload a preliminary version the night before, just in case Work on the schedule with the whole team backwards Identify leads that are responsible for content with a deadline attached The editor needs a week time to merge everything, at least The schedule is a great document to have in the appendix

Peer Review Students are good at spotting each other’s mistakes By having sections of content circulate a common style will evolve Students own the Engineering Notebook, NOT Mentors, NOT Teachers

Post Mortem The feedback BEST provides is incredible valuable Your team will have to do the same thing next year again Your team can see how your own scoring maps to the judges scoring