Crafting Effective Technical Documents for the Engineering Field

Episode Transcript

We all know a part of engineering is actually writing up our results. Some of us like to do it and some of us really just don’t like to do it <laugh>, but it’s a necessary thing because it’s a mode of communication, a mode of communication for a lot of people for different reasons. We may be writing technical reports about the results that we got and coming to a conclusion about our decision about the test results. What are we going to do next? We may be writing protocols for test procedures in order to get those results, and we need to communicate that protocol for other people to independently run the test and do it well, and then there’s things that can happen. The root cause, analyses of failures that happened during tests. All of these kind of writings are things that engineers need to do. It doesn’t always make sense to pass it off to a technical writer. When we’re writing these are, are they getting kicked back to us by the reviewers to add more detail or are we feeling like it’s a little bit fruitless because we don’t feel like the reviewers are actually reading it? They’re not giving us any feedback at all. How do we know when our piece of technical writing is complete? I have a trick for you that I use all the time and it has to do with ghosts. Let’s talk more about it after the brief introduction.

Hello and welcome to Quality During Design, the place to use quality thinking to create products, others love for less. Each week we talk about ways to use quality during design, engineering, and product development. My name is Dianna Deeney. I’m a senior level quality, professional, and engineer with over 20 years of experience in manufacturing and design. Listen in and then join us. Visit quality during design.com.

Do you know what 12 things you should have before a design concept makes it to the engineering drawing board where you’re setting specifications. I’ve got a free checklist for you and you can do some assessments of your own. Where do you stack up with the checklist? You can log into a learning portal to access the checklist and an introduction to more information about how to get those 12 things. To get this free information, just sign up@qualityduringdesign.com. On the homepage, there’s a link in the middle of the page. Just click it and say, I want it.

Technical writing. It is a skill that needs to be learned. I remember early on in my engineering career, I had saved my technical writing textbook from college, and it was really useful. It takes practice, practice, and thankfully engineers get lots of opportunities to practice their technical writing. Our companies probably have templates and forms that we have to fill out and that can be helpful for the company. Everything is in the similar format in the same place. I used to be a little annoyed at that, but as I’ve grown to be a more mature engineer, I understand the purpose of it to make sure that all the information is captured. It’s easier for the reviewers when they’re looking for information in a particular spot. As a quality engineer, I was an independent reviewer on a lot of other people’s technical reports, and there were certain things that I looked for regardless of whether a template was used or not, there’s a practicality to it.

Also, you’re working with somebody else to capture the information that we think we might need. There’s a simple guideline that I use to be able to help me with technical writing and in the technical writing of others that I review, and it really has to do with the audience. Any writing that we do, we want to think of the audience. Well, when we’re writing these technical reports, who is the audience? The people reviewing it. Not necessarily. We have to think a little bit bigger than that. We have to think of the ghosts of technical writing. Past, present, and future. I’m sure you’re at least aware of Charles Dickens’s novel, A Christmas Carol. He wrote it in 1843. It’s the story of Ebenezer’s Scrooge, and he’s an old guy who is miserly. He likes his money. He doesn’t want to share it. And he’s visited by four spirits: his former business partner, but then also the spirits of Christmas past, present, and future (or yet to come).

We can steal from Charles Dickens’s idea to think about the audience that we’re writing for when we’re doing our technical writing pieces. Our audience are the people who are reading it now for approval or are reading it tomorrow after it’s published. It’s also written to the future, and we can think of where we’ve been in the past. Taking these different viewpoints of our audience with our technical writing will make sure that it’s the best it can be, and it’s simple.

Let’s talk about the spirit of writing to the present. We do want to write our technical pieces for who is reading it now, which is probably our project team or our cross-functional team. They are making decisions about what to do with the project based on what they’re reading in the technical report. Also, if we’re in a regulated industry, we may be writing for auditors, third party independent people that are coming in to ensure that we’re doing what we say that we’re doing and that we’re complying with regulations. They look for evidence of that in the reports that we write, and they may come across ours, so I would consider those kinds of reviews also within the realm of writing for the present. In writing for the present, people need to have enough information about what we’ve done, captured in the report so they understand what we’ve done and can decide if they agree with the conclusion, need to see more tests or a different analysis, and then make a decision.

Now, in the spirit of writing to the future, we want to think of another engineer, maybe even 10 years from the time that we’re writing our report. They have the same technical knowledge as we do. We want to write our technical writings so that they can duplicate our results or understand the conclusion that we made and how we got there. This is really clear if we think about a test report and a test protocol, another engineer, 10 years from now, we’ll be able to pick up our report, gather the same equipment, perform the same test, and get the same results, and that’s without us being there because by then maybe we’re working on some other super duper project somewhere else. In this sense, we’re creating technical writings that are independent for themselves. Now, that’s not to say you have to include the whole world in your one document, make references to other documents. As long as that future engineer will be able to pull all the pieces together and recreate what we did, that’s a good check for a technical writing piece.

And the last check for our technical writing to see if it’s complete: we can write to the spirit of our past selves. When we’re in the midst of a project, we’ve got our fingers on the pulse of everything that is going on with the project. We know what the other engineers are doing. We know what manufacturing is developing. We understand how all the puzzle pieces are fitting together. However, in the spirit of writing to the past, our past selves, before we got involved in the project, didn’t know anything about what was going on and what we were trying to accomplish. So when we we’re doing our technical writing, can our past selves from six months ago understand what’s going on and what we’re trying to accomplish?

With any given project there are lots of reports and technical writings, and there’s honestly a lot going on, right? A lot of different people are producing different reports. In the end, we’ll have a dossier in the general meaning, a collection of files about the project that tells the story of how it was developed, what was learned along the product development cycle, the decisions that were made, and ultimately how we got to producing and releasing the product to market.

The term dossier is used at least in medical device manufacturers, but I mean it more in the general sense of a dossier. Even if you’re not working in a regulated industry, having this dossier, this collection of documents will help other new product development teams in the future to kick off their project. We’re not starting from zero anymore. We’ve learned a lot in developing this one product. We can use what we’ve learned to develop other products, and we have a record of what we’ve learned in the dossier and in our technical writings. If we’re having field failures or the performance has changed over time, what has changed about its use environment versus how we tested it? Maybe we didn’t test it to the environment that it’s being used in or having the dossier would be able to tell us that information and help us get to the root cause of the problem.

When we’re working on future projects, even if we didn’t use what we did in the past to start the new one, we’ll have some memory or understanding, “Hey, didn’t our other product do this too? Didn’t we see these kinds of results and what happened there?” We’d be able to look back at the report and find out why these are all ways that we might be able to use our technical writing to help us in the future.

What’s today’s insight to action? Engineers need to write stuff down. It’s part of the job description and part of our responsibilities to do. With any writing, we want to think of the audience, but we can expand that to ensure that our technical writing is the best that it can be. We can write in the spirit of the past, present, and future. We can use these spirits as we’re writing, and we can also run our final drafts through the filters of the spirits, and that will definitely help us communicate our technical expertise to others.

If you like this topic or the content in this episode, there’s much more on our website, including information about how to join our signature coaching program. The quality during design journey. Consistency is important, so subscribe to the weekly newsletter. This has been a production of Deeney Enterprises. Thanks for listening!