Technical Document Redesign

Primary tabs

5 posts / 0 new
Last post
Josh Brown's picture
Offline
Joined: 24 Dec 2014 - 12:43pm
Technical Document Redesign
0

I work as a technical writer at a security firm. One of the documents our firm uses in all government contracts is called PVT Procedures. This document contains test procedures that our installation technicians use during equipment testing events. Whoever designed said document was more familiar with the equipment concerned than they were with principles of typography and document formatting. I am now redesigning the PVT Procedures layout and so seek directive input from you all regarding what I've done so far. I've attempted to attach sample before and after images. Hopefully you will be able to tell which is which. Note that I'm limited to working with MS Word on all documents.

J. Tillman's picture
Offline
Joined: 27 Sep 2009 - 11:31am
0

5.1 Card Reader Tamper Test
These things go together, so put them together. Eliminate the unexplainable space. If these two things are together, the reader's eye will be drawn to Card Reader Test, which is what you want. Putting Card Reader Test in the event column serves no purpose.

I would consider putting Event and Expected Results beneath 5.1 Car reader Tamper Test. The Event and Expected Results are part of the Tamper Test, not floating above it. Then you could put Event even with the event column just as Expected Result is (already) even with the expected result column. Then rename Event with something more clear, like Tester's Actions.

Real time communications.....
What does this mean? Shouting? Each person has a cell phone? What?

Miscellaneous hand tools.....
So the first writer had no clue either. Can you reference something here?

In the Expected Results Column, The system should not allow...
What does this mean? What is actually supposed to happen?

Something that jumps out at me overall is the stilted, third person style. Most instruction is now written in an informal second person style. For instance: "Real time communication with the operator should be established." Now writer's would tend to say: "You must be able to talk to the operator during the test, such as with a phone line..." Maybe that's beyond the scope of this project.

All of this is just my opinion.

Reynir Heiðberg Stefánsson's picture
Joined: 19 Nov 2010 - 11:15am
0

I would do something similar as well.

5.1 Card Reader Tamper Test

Actions Expected results
-----------------------------------
Action 1 Result 1

Action 2 Result 2

As long as the installation techs know and understand the jargon, second v third person is hardly vital.

By the way, what is supposed to happen in the first case is that the system must not/never ignore the tamper switch tripping. To ‘mask’ something is to cause it to be ignored.

Real-time communications… Whatever it takes, man. Shouting may do at one site, but the next may well require a mobile phone or a walkie/talkie. Some things just can not be nailed fast. Same with the handtools. They depend on the hardware the switch is fixed to the case with.

Aside: I would change the Initial Conditions from “should” to “must” as the test requires tech and op to be in contact, right?

Josh Brown's picture
Offline
Joined: 24 Dec 2014 - 12:43pm
0

I'd designed "event" and "expected results" as floating headings to try to streamline. Because there are often several test sections (5.1, 5.2...) within a test, one floating heading can take the place of four or five fixed headings. I'll move the headings in with the test sections, though, and see how the two formats compare. Thanks to J. for pointing out that inexplicable space, and Te, you're right about "not allow mask" vs. "ignore," and "should" vs. "must."

Misbourne's picture
Offline
Joined: 5 Dec 2014 - 7:04pm
0

As a science guy, the first draft looks depressingly like one of my undergraduate lab reports. I don't have an education in design, but I would consider introducing some hierarchy by using two contrasting fonts. Headings in a big thick sans and body text in a plain serif will emphasise the text's structure. Definitely agree with you that eliminating the columns at the top would be nice.

Here's my redraft, using your text more or less (though I agree second person would be better). The spacing of the document is a bit erratic - you could tighten it up.

With Actions/Expected results, you have a problem: do you put it under or over the first test heading? I put it under, you expect to find it under the heading. Then for future test sets I didn't bother putting it in again, since you know what the columns mean after that.

You could also put the test instructions in sans-serif to make them stand out, which might help. But I felt that made the document a bit blocky and awkward, as the linespacing of the test instruction and test result won't match.

For fonts, I've used Twentieth Century MT and Garamond, both fonts included with Office, since a chunky geometric sans and a plain serif make a good contrast, I think. Twentieth Century is called Tw Cen for some stupid reason by Microsoft. As Microsoft's Garamond is a bit lame, I actually used the much nicer EB Garamond, which you can get for free. (Obviously there are many premium fonts nicer than either of those, but I thought I'd go with ones I'm sure you have already.)