Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

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.

share|improve this question
    
"Technical subjects" is pretty broad, but it sounds like you're specifically asking about technical-sales/proposal documents. If so, could you clarify your title? Thanks. –  Monica Cellio Oct 28 '13 at 13:15
    
    
90% of tech writing seems to be software documentation, not sure if this is relevant, also I'm looking for a cheat sheet, not a book. –  mart Oct 29 '13 at 8:49
    
any way to make improve this question? –  mart Oct 30 '13 at 13:14

1 Answer 1

up vote 5 down vote accepted

Okay, let's do a cheat sheet.

  1. 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.
  2. Be consistent. Always refer to things (components, concepts) by the same name. Explain new terms the first time you use them.
  3. 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.
  4. Make sure your writing is unambiguous. Is "the right handle" the handle on the right side of the control panel, or the correct handle?
  5. When in doubt, ask a colleague (preferably a non-expert) if he can make sense of what you've written.
  6. 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.

share|improve this answer
2  
For the OP, point 3 is more difficult, having a mixed audience. Including an executive summary at the beginning (and perhaps a light intro in major sections) and otherwise supporting selective reading (for both kinds of readers)-e.g., primary headers that communicate well to the less technical (including communicating "this section is highly technical"). Limiting 'marketing speech' to less technical portions might both increase its positive impact (non-techs will get it) and reduce the negative impact for techs (who often dislike such as lying and time wasting). –  Paul A. Clayton Nov 5 '13 at 2:35

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.