bell notificationshomepageloginNewPostedit profile

Topic : What are best practices when writing technical descriptions? Occasionally, in my job as an engineer, I write process descriptions of the technology we are selling. Those are part of commercial - selfpublishingguru.com

10.01% popularity

Occasionally, in my job as an engineer, I write process descriptions of the technology we are selling. Those are part of commercial offers, intended to win the customer. Those are bundled with drawings, technical offers and the like. We are selling complex plants and it is safe to assume that there will be an engineer reading the offer, and maybe other management staff. I write these in German and English. This is not something I do very often, but it crops up.

So far, the procedure has been to take the last document we did that is relevant or similar to the job on hand, and edit or expand it. There's lots of marketing speech in older documents, some of it (I think) is only understandable when one knows the technology. So when I do a session of copy, paste, edit, I change rather a lot.

This answer to another question suggests reading similar documentation and understanding their style. This seems to be good advice, but only partly doable because the exact style of documents I write is one that I hardly get (I write offers for plants and read offers for components).

Now, I'd like to have a few best practices or guides to follow when doing this, because I want to arrive at a consistent style that actually conveys what we are trying to say.

Load Full (1)

Login to follow topic

More posts by @Rambettina586

Login to post a comment!

1 Comments

Sorted by latest first Latest Oldest Best

10% popularity

Okay, let's do a cheat sheet.

Be logical. When you describe the technology, describe it in an order that makes sense to the customer. Use a top-down approach, starting with an overview and delving in the details only when you have given the reader the context he needs to understand them.
E.g. when you describe a machine, follow the flow of products through a machine.
Be consistent. Always refer to things (components, concepts) by the same name. Explain new terms the first time you use them.
Be aware of your audience. Your question indicates that you already are, so that's good. Will they be able to understand what you've written? They have your level of education, but not your experience with the technology.
Make sure your writing is unambiguous. Is "the right handle" the handle on the right side of the control panel, or the correct handle?
When in doubt, ask a colleague (preferably a non-expert) if he can make sense of what you've written.
Avoid overloading. Each sentence should have a single subject (e.g. one feature of the machine). Avoid run-on sentences. Each paragraph should have a single subject (e.g. one module of the machine)

Point 3, 4 and 6 become even more important if your audience includes people for whom English/German is a second language.

Load Full (0)

Back to top