Latest posts by techwriter (see all)
- Hazards of Poorly Written Technical Documentation - December 26, 2016
- Get an ‘A’ on Your Next Research Paper With These 6 Simple Steps - November 28, 2016
- An Amazing and FREE Source of Magazines and Periodicals — ISSUU - November 25, 2016
Always look to see if you can improve your sentences by applying some of the principles illustrated below in sentences taken from real manuals that I have edited for a client:
(1) >>> If a sentence has two WITHs, eliminate at least one of them:
ORIGINAL SENTENCE: After the initial power-up, the display should show the PRO-FIX operator screen with a rectangular pop-up window with the following two “Logon ID” and “Password” messages.
BETTER: After the initial power-up, the display shows the PRO-FIX operator screen where a rectangular pop-up window displays the “Logon ID” and “Password” text fields.
(2) >>> Use active voice:
ORIGINAL SENTENCE: If the Operator Logon window is not visible, any key that is pressed will bring up the window.
BETTER: If the Operator Logon window is not visible, press any key to bring it up.
ORIGINAL SENTENCE: Once the startup condition is attained, the first-time user may log on to the M-26 PANEL.
BETTER: After the startup, the first-time user may log on to the M-26 PANEL.
ORIGINAL SENTENCE: It is strongly recommended that the PRO-FIX default account be
disabled and new ones with secure passwords are added before the system is certified for normal everyday use.
BETTER: Disable the PRO-FIX default account and add a new one with a secure password before the system is certified for normal everyday use.
(3) >>> Avoid multiple use of the same verb within the same sentence.
ORIGINAL SENTENCE: As discussed earlier, the GET command is used to configure the M-26 PANEL for use in the G-24 network.
BETTER: As discussed earlier, the GET command is used to configure the M-26 PANEL as a part of the G-24 network.
(4) >>> Avoid sentence fragments with verb participles:
ORIGINAL SENTENCE: If using RS-485 wires to communicate between the PRO-FIX server and M-26 PANEL, ports P2 and P3 are available and configured as slave buses by default.
BETTER: If you are using RS-485 wires to communicate between the PRO-FIX server and M-26 PANEL, ports P2 and P3 are available and configured as slave buses by default.
ORIGINAL SENTENCE: The LAN cabling can connect to Ethernet A or B connections.
BETTER: The LAN cable can connect to Ethernet-A or Ethernet-B terminals.
ORIGINAL SENTENCE: Configuring the M-26 PANEL in the preferred order will also shorten the amount of time that’s required for configuration by reducing the amount of back-and-forth item modification.
BETTER: Configuring the M-26 PANEL in the preferred order also shortens the configuration time by reducing the amount of back-and-forth modification of the individual items.
Have a great and clear day!