General Engineering Introduction/Documentation

quiz

You are not an engineer until others can replicate what you have done ... without your presence ... without your words .. without your physical personality on the planet.

There are four major forms of engineering documentation: notebook, project, tutorials and presentations. The focus below is on project documentation. Project documentation is electronic and splits into two categories: personal and team.

Background, Definitions

Crafting .. no documentation

Crafting is where the designer actually produces the artifact directly. This is no documentation. No one else can produce the artifact. The great Egyptian pyramids, the wall of China, the Mayan temples were all crafted. Showing, talking and doing have little to do with engineering. And for this reason today we can only speculate how they were built.

Trade or craft economies have existed without documentation. There were no engineers. The modern world depends on engineers documenting.

Replication

There are plenty of geniuses that have existed and will exist. But without documentation, nobody can fix, improve, replicate, or explain. Without documentation, the fruit of the genius will die.

Replication is the primary objective of engineering documentation.

Replication involves documenting for two very different audiences: technician and other engineers. The technicians are going to want to repeat your steps to success exactly which leads to tutorials. Engineers are going to read these tutorials to get to the unknown edge of the technology quicker. But engineers are going to want something else. They want to know how the team was organized to step out off into the abyss. Engineers want to know how dead ends were recognized. Engineers want to know the symptoms, error messages, and failure mode details of what didn't work. Engineers want to know how tasks were split up. This is called project or problem documentation.

Expensive

Documentation can be more expensive than materials. Airplanes are now built with no physical world testing. Information about the airplane creates simulations that are now accurately predicting success. The information cost associated with some crops is larger than growing and harvesting. Pecans can be picked, husked, shelled, dried, and packaged for less than the cost of transportation. The information (packaging, transportation, marketing, support, life cycle) has to be engineered also. Engineering services or software is purely engineering information. This is why some introduction to engineering classes only grade the documentation, not physical success.

People, time, hands-on experiences are expensive and are getting more expensive. Engineers that can design without physical modeling, without purchasing kits, without lots of destructive testing, are going to be more successful.

Engineers Checking other Engineers

Governments force certain engineering disciplines to have every design document checked. Professional Engineers in the US have an embossed stamp that is impressed onto a document that has been checked.

Engineering documents have to be created. Sometimes they are thousands of pages. Three main groups of engineers are involved: those engineers that represent the government's interests, those that design the bridge and those that build the bridge. The same engineering firm can only do one of the three. This forces the creation of documentation. Engineering documentation becomes the root, the beginning, the heart of a project, not an individual engineer. These legal and procedural practices have forced the evolution of documentation in civil engineering.

Newer engineering disciplines seem to have to learn this Ethic all over again. One mind can not come up with all the possibilities that need to be considered. One mind can not switch from the creative flow to annal, detail checking very easily. Brilliance doesn't eliminate this need. A “Loan origination” software package was being rejected by bank branches. The problem? The software was “crafted” by one brilliant engineer.

Only in the hand off from one engineer to another does the design document grow independent of the personalities involved. In the software engineering world, the disciplined practice of pair programming and unit testing are exploring methods of checking.

Collective Mind

The collective mind of a group of engineers has to be mined. The lone genius engineer can be found isolated and working alone in some firms that are trying to build a patent portfolio. But this is rare. The opinions of all engineers, even engineers outside the firm have to be harvested. A collection of opinions, suggestions and resources requires a team of engineers working together at project documentation.

Best Practice

Only when there is a hand off from one engineer to another do “Best Practice” documentation standards have a chance to evolve. Open source software development is the beginning of software engineering because it provides a starting point for software documentation. Software is important because so much of all engineering today revolves around simulation, data collection, and analysis. Using any software package involves some form of programming.

Project Documentation

Goals

Every engineering company has its own method of documenting projects. Failed projects, open ended and currently active engineering projects are documented very differently than "successful" projects. Successful project documentation rapidly turns into theory of operation, repair manuals, operation manuals, etc. The goal of this course is to teach engineering documentation in a college freshman engineering context.

The goal of general engineering projects is to capture the creative design process of engineering as it unfolds with these objectives:

• Others can jump in, find a starting point and push the project forward
• Existing documentation serves as scaffolding to quickly build up expertise
• Project Managers/Instructors can see previous task evolution, time and materials consumed for planning purposes
• Opportunities for casual readers/other engineers to read through problems and suggest solutions
• Become a best practice implementation for a particular type of project

Personal

Portfolio

There are two places you need to electronically document your work. You need two types of information at your finger tips. One type is found on the internet. The other is personal and secured. Your physical notebook is the ultimate security. There are reasons you need to create your own secured personal electronic file repository:

• Internet information is constantly changing, you may need a snap shot of the past. Don't depend on the way back machine].
• Most people spread themselves all over the internet. Are you really going to be able to find that cool post in facebook or response you wrote in someone's blog 4 years from now during a job interview?
• The job finds you. Companies look at your on-line portfolio.

Every paper you write, every drawing you make, the syllabus of every course you take, every homework problem you scan, every bit of data you collect, every simulation you create, every version of every program you write, every resume you create, every photo and video you take needs to be at your finger tips. You will need them in the future. The people that have this information at their finger tips get better jobs, get on better projects, and worry less about certificates and degrees. There are some that believe that college education systems are going to move away from degrees and towards portfolios. You need to begin collecting the raw resources needed to build a portfolio. Where and how you do this could be:

• on a hard drive (hard drives eventually die)
• on a thumb drive (these eventually are lost or get a virus)
• in a school created personal folder (disappears when you graduate or don't pay your bill)
• Internet Cloud: Google drive, DropBox (or competitors)(worry about privacy, free services disappearing)

There are no perfect answers. The best pre-internet engineers could also put their fingers instantly on just the right catalog for the part needed, on the needed solution or the documentation of a similar past project. Before the internet, it was not the engineers with the best minds but the engineers with the best paper organization systems gained the most respect. Now the most respected engineers can find the 3 year old email attachment.

As of Fall 2014, this is best practice.

• Upload photos to wikimedia commons if you take the photo
• Do not load fair use of others graphics work to wikiversity
• Create a wikiversity id and build a profile in wiki user: space
• Do all your editing in wiki user space and then transfer to wikiversity article space when done
• Upload video to youtube, make public link with the word video and description of the video

Individual Weekly Summary

The personal weekly summary is done in wiki format within wikiversity.

The grading of the personal weekly summary has three parts:

• FORM .. electronic documents linked in a narrative, wiki format followed
• COMMUNICATION … created weekly task for team, positive comment for each team member, complete transparency so manager can see who did what
• WORK … pushed the project forward rather than just worked on personal learning curve and/or helped create design documentation on wikiversity page

Work points are for “pushing” the project forward and design. This means doing something significant. This is individual recognition and reward. Push points have nothing to do with hard work, money, massive amounts of time, failure or success. Push points are given for documentation of detail, the steps being taken and time taken. Failure will result in many more points. Success typically results in a tutorial.

A verbal summary of what happened during the week will not get you any push points. For example writing "I tried to run the android fight controller and failed" will not get you any project points. The problem is not the failure, the problem is that the failure was not described. What version of the android operating system running which filght controller on which computer in which virtual box? What was the error message? Can not find wifi or can not access the SD card? Notice the failure and begin asking a 1000 questions about it.

All failures, all documentation will go into a CDIO document that is negotiated with the instructor. The name of the CDIO document, the outline of it is where all project documentation goes. Most of the time this document will be created by one person. Each person on the team will be working on one CDIO document most of the time. It will then be handed off and checked by a team mate and the permission for publishing given by a team mate when the team is done.

Most of the CDIO document content comes from your notebook. The chaos and frustration written about in your notebook get organized and stripped down to sound byes. The pictures and video taken while writing in your notebook are then assembled into a an attractive story in the CDIO document.

Typically form and cooperation points have fixed maximums. Push points are unlimited. Push points can be up to 10% of the overall grade of the course.

Peer Review

Say positive things to your team mates about themselves. Practice praise. Plan it. Don't expect it to spontaneously erupt out of your soul when you are in the right mood.

Most schools have a system of support services that kick in when students stop participating. Most of these services are ineffective if team mates don't worry about each other. The person with problems most often seeks help too late. It is up to team mates to trigger these services. If a team mate does not have work to review, communicate with them. Relay this to the instructor so that the support services of the school can do their job.

Team

We

The goal of CDIO documentation is to hide personalities. Write them from the "we" perspective. You may be given someone else's CDIO document to improve from several years ago or yesterday. Some CDIO documents are worked on simultaneously by several people.

Engineering companies are generally reward engineers when a team is successful. Individual engineers within the company are secret, prized, assets of the company that are hidden from public view.

Many engineering projects can continue forever. They can branch, fork, shift direction, and merge. The same is true of the documentation. Anything written with an "I" perspective looks out of place.

Engineering projects are never finished. There are always next steps that can be thought of. But project documentation has clear boundaries. These boundaries are set by project managers who try to predict time, materials, people, money and space. These resources combine on the business side into definitions of finished that are associated with profit. "Good enought" captures this type of "finished."

Project documentation is how engineers pass project responsibility to another team. Engineering projects are never “finished.” Each engineering team typically completes only a small part of a much larger, multi-team or multi-year project.

The goal of this course is to work on projects at an even pace. Rapidly completing a project at the last moment or in the first week is discouraged.

A minimal outline of project documentation can be found in wikiversity.

Project Success

A project is judged successful if it solved the problem as described in the problem statement. The problem statement is a fluid document that can be revised, with the consent of the client (or instructor/project manager).

Design

Engineering Design is the next major section in this book. They are loosely organized first into categories of Art, Science and Business. Ultimately, one of these categories will dominate an engineering project. Learn to think in these terms first rather than mechanical, electrical, civil, chemical or biological engineering.

The paperwork/documentation part of design focuses on CDIO which is listed in the business section where engineering documentation of "yet to be successful .. failures" is the hidden value of an engineering company. Within this context there are more specific tasks that individuals and teams can do when creating the CDIO documents.