Early in my career, I had a remarkable discussion on the importance of documentation. I was (and still am) of the opinion that everything should be documented, at least to the extent that it does not get in the way of the actual work. After all, the only difference between engineering and screwing around in the yard is writing things down. My colleague, who was far more experienced than me, had a very different opinion:
People who can’t understand the design shouldn’t be looking at the drawings. People who can read the drawings should be able to interpret the design without additional documentation. Ergo, documentation is useless.
To paraphrase the sentiment in a coding context:
i++ // increment iThe above is probably a bit redundant.
I agree with the logic of my colleague. Managers and sales reps have no business looking over engineering drawings, and any competent engineer can surmise the intent of most, if not all, design features directly from the drawings.
The point of documentation, however, is to highlight what is missing from the part or drawing. Any code literate person can see that we are incrementing i. What I may be interested in is why we aren’t, for example, iterating over a list? Did we consider it? If we had, are the assumptions that led to an increment-based implementation still valid?
Consider the following hypothetical product engineering example. A client required a complex system with a rapid initial prototype, followed by an optimized product for series production. The prototyping team dutifully created a working system, meeting all client requirements at minimum cost. The optimization team, among other design innovations, discovered the following system which was a prime candidate for optimization:
This is quite obviously a tension member, and could be easily and cost-effectively replaced with a nylon strap. Absent further information, the optimization team designs a nylon strap and sends the product to production. In the field, the nylon strap fails prematurely and an investigation is performed.
What the optimization team did not realize was that the duct tape strap also served a critical purpose in coupling the mass’s oscillations with the supporting beam. The beam underwent rapid oscillation during operation, and without the tackiness of the duct tape, the nylon strap slid and frayed. Further, as the vibrations were partially absorbed by the slipping action of the strap interface, the hanging mass was less effective as a damper and other elements of the system were exposed to over-design loads.
This is obviously a highly contrived example, but highlights one of the most important forms of documentation there is, and the missing component of the conversation I had with my colleague all those years ago:
Requirements Management
Fundamentally, to manage a part or subsystem through its lifetime, one must know what it is required to do, and what it needs of the rest of the system to operate. To whit, the part has its requirements and its assumptions. Any change to these require a change to (or at least review of) the part, and a change to the part which impact its fulfillment of requirements or the assumptions upon which it is designed will have implications for other elements of the system. To evaluate a part, one must have all three: the requirements of the part, the assumptions that went into the design, and the drawing of the part to determine if the design is “good” relative to its inputs.
Revision History
Another important type of documentation is revision history. In the design process, it is rare that the first idea that one comes up with is the best or even a functional solution to the problem. It is likely, however, that the first idea is obvious. By this I mean it is likely that the next person to work on this problem (be it a colleague or simply your future self, long after you’ve forgotten about this task) will come up with this same bad idea. It is therefore useful to tell this future person that you explored this concept, and found it to be lacking in some way.
In a published drawing or engineering artifact, revision history is only present with a “Revision 1.7” note or similar method of ensuring the workshop and the design team are talking about the same version of a given part. While clearly quite important, this method loses the “ideas log” mentioned in the previous paragraph. Obviously, however, the workshop has little interest in the history of the part and it is therefore good that the drawing lacks the traces of brainstorming from the design team.
So where do you put the design history of the part? Well, in an archive of course! Your design team, if they’re saving their design history, would therefore have a working directory that looks like this :
Part_foo_rev_0.8.prt
Part_foo_rev_0.9.prt
Part_foo_rev_1.0.prt
...
Part_foo_rev_1.5.prt
...
Part_bar_rev_3.14159.prt
...Unfortunately, the above is not satire. I have seen working directories with dozens of copies of the same report, separated by version number (or worse, by text date, month-day-year). Version control is a well understood problem, and version control software (git, subversion, mercurial) is an excellent solution. I would go so far as to say that any serious work of any kind would be improved by saving it in a version control repository.
Please, learn to use version control, and teach your teams how to use it. Here is a blog entry introducing the concept, and here is a short video game teaching you how to use git specifically.
Proof of Work
The last form of documentation I would like to talk about is the dreaded engineering report. In a regulatory environment, you must demonstrate that certain problems or concerns have been considered, and often that processes and procedures have been followed.
There is no way around this requirement, as it, along with testing, is the primary method of communication with the regulatory body. What can be done, however, is automation of process checks and, ideally, automatic conversion of analysis into documentation of that analysis. This is one of the stated goals of Birdbrain EDM.
Other types of Documentation
I am glossing over other types of documentation, like marketing docs, user docs, etc. They are certainly important, but are typically not the responsibility of the design team directly.
So why does everyone hate Documentation?
I hope I’ve demonstrated that proper documentation is really quite foundational to good engineering practices. Disdain for documentation is nonetheless nearly universal.
I think its because writing docs just isn’t fun. By the time you’re writing down what you’ve found, the puzzle is solved and you want to move on to the next task. Going back and documenting your day’s work feels pointless and is uninteresting. Unfortunately, it is fundamentally what your boss is paying for, at least in part.
In the software world, automated documentation tools like doxygen and the above mentioned version control systems take away much of the burden of documentation. One of the goals of Birdbrain EDM is to bring this doc automation into the hardware engineering world. Specifically, the design goal of Birdbrain EDM is to achieve full documentation coverage for at most 10% increase in total workload.
Let’s see if we hit that target!
Leave a Reply