Synergy Technical Editing ProjectEditing • User Guides

Rhetorical Situation

I began working for Synergy on a part-time basis in the summer of 2018. I was first tasked with transferring their user guides into Markdown, a lightweight markup language used for placing information on websites.

In the Spring of 2019, I proposed to Dr. Tharon Howard the possibility of beginning my studies in technical writing with a technical editing project involving the same user guide files. The small company of Synergy maintains software related to logistics planning. The Territory Planner is a mobile application created in 2005 to help truck drivers determine the best route to their destination taking into account various stops and factors such as driver fatigue and labor laws.

Audience

The audience of the Territory Planner User Guide was the truck drivers who would use the user guide after having been trained to use the tool. Rude mentions that, "There are a few purposes for reading technical documents. Readers use the document in order to act, solve a problem, make a decision, operate equipment, or to get information.” Similarly, the main goal of the user guide would-be to troubleshoot problems with the application and learn is used. This would be a task-based user who is interested in a particular part of the application that they may not be familiar with.

Constraints & Goals

This goal of the study was to uncover the major usability and technical problems that were contained within the Territory Planner User’s Guide. In the process of this project, a style guide was created and approved by Synergy to be implemented in the course of editing. Issues mentioned in the style guide are listed as recommendations in the document itself with the corresponding rule listed in the style guide cited as evidence of the problem. This project was constrained by the time in the semester that I had to complete both the style guide, scholarship reading, and editing.

Process and Scholarship

I began with the creation of a style sheet for Synergy. For the purposes of this project, research was performed into common styles related to the technology and software industries. In this research, a new style guide was created specifically for Synergy, which can be found here. The style guide follows closely the rules presented in the Microsoft Style Guide, as well as the IBM Style Guide with reference to Google’s Style Guide as well. In discussion with the client, we determined that the more formal style used by Microsoft and IBM would best match the tone of the company rather than the no-nonsense, informal tone of Google. For this reason, these style guides were used as templates in the editing of the User Guide.

Carolyn Rude, in her book on Technical Editing, outlines the main functions of technical editors as the readers who prepare documents for publication and make documents effective for readers. In following these principles, this technical editing project had the goal of making the information of primary importance first and place key concepts in prominent places to ensure the document will be appropriate for the community. This included checking the information for accuracy, completeness, and conciseness as well as removing visual or verbal noise which can distract readers, making information more difficult to comprehend. This project included phases of editing involving research and close reading. The steps moved as follows:

1. Creation of Style Guide

   After determining the document was very technical, the editor realized the implications of changing small grammar things such as symbols or capitalization. There are usually style guides available for this editing, and with the lack of an existing company style guide, I created one for the company with research into existing style guides and careful examination of every principle.

2. Copy Editing and Proofreading

   Copyediting prepares a text for printing while proofreading is done to verify that a text has been printed correctly. Proofreaders do not change choices but verify that they have been incorporated. Proofreaders only change text when a copyeditor has overlooked errors. Proofreaders much reviews alignment, spacing, and clarity of letters to ensure print quality. Both proofreading and copy-editing were completed on the document. The proofed document can be found here.

3. Substantive Editing

   Usefulness depends on a document’s concept that matches the needs of the readers. Substantive editing is evaluating a document’s concept. The substantive editor will suggest ways to improve the document. While copy editing with increase the credibility, substantive editing looks beyond words, making the document more functional and appropriate for readers. In analyzing the Territory Planner User’s Guide it was necessary to analyze the text in terms of audience needs. This required analysis of the audience and a determination that the document was not meeting the needs of the audience who will come to the document when errors arise.

4. Organizational Editing

   Technical documents must organize information to ensure readers remember it. Templates help readers learn information including major and subordinate components. These components should be developed early to helps readers locate the appropriately stored schema in memory. The beginning of the document should presents concepts by identifying the topic and placing it in context. In analyzing the Synergy Territory Planner User’s Guide, the recommendation made in terms of the organization was to move from general to specific and restructure the navigation to reflect the change.

5. Visuals

   Visuals require copyediting and substantive editing to check for accuracy, correctness, consistency, and completeness. Visuals need to be in line with readers’ expectations, and often readers expect information in visuals. It was determined in editing the visuals of the Synergy Territory Planner were too numerous and were not each adding essential information to the User’s Guide. I marked such visuals to be removed in the proofed version of the guide.

Findings

This study was designed to uncover the major usability and technical problems that are contained within the Territory Planner User’s guide. In the process of this project, a style guide was created and approved by Synergy to be implemented in the course of editing. Issues mentioned in the style guide are listed as recommendations in the document itself with the corresponding rule listed in the style guide cited as evidence of the problem. Below is a list of recommendations that will potentially increase the usability of the Territory Planner users’ guide as well as correct mistakes in the document to bring them to the standard of current technical editing guidelines.

Restructuring of Navigation to general toward specific

Restructure the manual toward a task-based guide based on common user errors

Use sentence-style capitalization throughout

Change all mention of the user to lowercase “user”

Shorten all processes with arrows to denote where on the page to click.

Use more concise, simple language

Change focus from overview to user task completion

Read Full Synergy Technical Editing Reccomendation Report