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.

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?

share|improve this question
    
How about an index or glossary of terms in the front or back matter? –  Lauren Ipsum Jan 31 at 17:33
    
I think I'll give it a shot. –  mart Jan 31 at 18:19
    
Can you say more about how the documentation will be used? You said a sales document but it sounds like you're writing instructions. Will your readers be trying to take actions based on the documentation, or is the purpose to give them information so they can decide whether to buy your product? –  Monica Cellio Feb 3 at 3:41

2 Answers 2

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.

share|improve this answer

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.

share|improve this answer
    
This is how I would approach it as technical documentation, too. I'm not sure how the sales aspect figures in, though. We need to know more about how this will be used. –  Monica Cellio Feb 3 at 3:40

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.