How should I handle repeating parts in a technical description?

Question

I'm about to write a technical description for an industrial process. The description will follow logical blocks, or blocks from the PFD of the process. This a sales document aimed at engineers. Because of the sales aspect, I need should emphasize all the elements that make us unique. Several parts will repeat throughout the plant, other parts I need to describe that can hardly be placed in one specific logical block - like interconnecting pipework or control.

My idea is to describe components when they first show up as a subchapter of the block they are in, and reference this subchapter when a component shows up in another block. Is there a better way to do this?

Edit to add: An alternative would be to have the component descriptions in every place the component shows up. Some would be repeated two or three times. This would pad the document. The pro would be that a reader who just looks up one part of the process does not need to jump around the whole text, but I would have to trust my readers to skip the parts they already read elsewhere. What to do?

Answer 1

You say it's a sales document, aimed at engineers. In that case, describing every part of your process in detail -- including the non-unique ones -- seems to me both unnecessary and counterproductive. Your readers will get bored out of their minds, will start skimming through your document, and will probably miss the unique aspects of your process. Result: no sale.

My advice is to have an executive summary of the process at the front, in which only YOUR unique stuff is detailed. Everything else in the process would be described as succinctly as possible. Then, the main body of your document would repeat the process description, but explaining all parts of the process (although still highlighting your unique stuff).

A glossary of terms is also a good idea. In the text, use a different font for terms in the glossary, so readers know they've got help if they want it.

p.s. My primary job is scientist/engineer.

Answer 2

In an instruction manual I would expect every section to me maximally self-contained. If I want to know how to change some setting in some appliance, I don't want to leaf back and forth following references to other parts of the document. I want quick results, not learn how this machine works.

If you write for engineers, who, if I understand correctly, will have intimate knowledge of your product, you can safely assume that they will familiarize themselves more deeply with this document, because they will want to evaluate how it works and what problems they might face if they chose to use it.

In such a situation, I would expect a technical description to explain the basic principles and functions in an introductory chapter (if they are unfamiliar to your readers) or an appendix (if you think they know most of it but might want to look something up or see how you do this), and then refer to these basics in the descriptions of the overall process and practical usage.

As for the structure of the whole document, if it is not technical documentation (which might be ordered alphabetically or hierachically by component) but an introduction for experts unfamiliar with your "machine", I would expect some kind of ordering narrative or storyline. This could follow the incoming raw materials or pre-assembled parts through the process until they leave the factory when they have been assembled.

If the process is not linear, tell it like a story with mulitiple protagonists: start with one and tell his story until he meets the girl; then switch to the girl and tell her story until she meets the man; then continue with their story, until they separate; when they separate, tell their individual parallel stories one after the other, until they come together again; if one spouse has an affair, halt the main plot and insert the story of the third character until he meets the woman or man; then coninue the main plot with all three protagonists; and so on.

What I mean, if it did not become clear, is to pick one subprocess, ideally the one that starts first or is most central, and follow it through to the end. When other processes come into play, insert their descriptions where they "meet up with" the main process. If something repeats, refer back to the relevant description.

If you can summarize the central aspects of the section you refer to in one or two sentences, do so. That helps your readers to jog their memory, they don't have to re-read it (but may, if they forgot or skipped it earlier), and they are not bored by reading anything twice, because the summary is concise.