: Re: 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

@Ogunnowo420

Vote Up Vote Down

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.

(0)

Login to post a comment!