TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I write training materials for technical support agents in a call center. They assist techs who install security systems in the field so their managers prefer to call them "field support" agents.
When a new security panel or new upload/download software hits the market and is going to be used for our field support agents I am asked to "leverage existing training materials/documents" to create my own.
The documents I'm given are usually install/user/owner manuals written by the manufacturers or software developers. Sometimes I can copy/paste or retype small portions and use existing screen shots, but I prefer to get my hands on the software myself to get personal experience and high-quality screen shots.
Rewriting these "existing" documents takes more time than if I were to interview a SME because while I can ask for clarification in a SME interview, I spend a great amount of time excruciatingly attempting to figure out what the original writers meant.
If I obtain existing documents from a writer, it is usually my predecessor writing about an earlier version or another department's materials that are written for sales, billing, etc. These materials are easier to understand and edit than installation manuals and take about the same amount of time as writing from scratch.
In general I find that documents I've written from scratch are shorter and more concise than "leveraged" documents.
Occasionally I'll hit the jackpot and find a document that requires only minor edits to be great.
I like the earlier comment about writing conventions and having to remove a lot of quotation marks. We use quotation marks for "screen names" and specific text or numbers that must be typed in a field exactly (e.g. Type "832" in the Event Code field). We use bold for field names and square bold brackets for [Buttons]. Our department uses specific words for actions too. People don't hit keys, they press them. People click click a mouse. The biggest offender is "hit." Since we spend a lot of time using phrases like, "Type 'ABC' in the XYZ field, then press [Enter]" we prefer to use 'type' rather than 'enter' when describing the act of typing data on the keyboard while the cursor is in a specific field. Otherwise much if our documentation would look like this:
Enter ABC in the XYZ field, then press [Enter].
I suspect it's a style choice rather than a universal rule.
Raphael
Sent from my iPhone
> On Sep 24, 2014, at 4:51 PM, Ron Hearn <rhearn -at- central1 -dot- com> wrote:
>
> You're right about the time it takes to "edit" some of these documents that just need to be cleaned up (someone once told me that a document just had to be "tarted up"). This is especially true when the writer has used their own standards and style conventions. I hate it when the writer has put all field and button names, messages etc. in quotation marks, when the document style guide only allows quotation marks in specific situations (or not at all), meaning the person editing the document has to go through and remove them all, and then insert whatever the standard is, e.g. Bold for field names.
>
>
> Ron Hearn
> Documentation Specialist
>
> Central 1 Credit Union
> 1441 Creekside Drive
> Vancouver, British Columbia, Canada
> V6J 4S7
>
> rhearn -at- central1 -dot- com
> Tel: 604.730.6391
> Fax: 604.730-7792
>
> -----Original Message-----
> From: techwr-l-bounces+rhearn=cucbc -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+rhearn=cucbc -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Lauren
> Sent: Wednesday, September 24, 2014 1:09 PM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: Writing vs. Editing
>
> This question really depends on the context of "edit."
>
> I have had people tell me, "We did most of the writing, it just needs to be cleaned up," so I assume I will just need to edit a document. When I get the document, I see that it needs a rewrite and many workarounds just to conform to the standard required of the document. In these cases, it takes me two or three times as long to "edit" the document than it would have to write the document from scratch.
>
> Editing the work of a bad writer or, worse, a non-writer who thinks they can write is cumbersome and tedious. Editing my own work or the work of a good writer is no easier or harder than writing, since I use the same skills for both.
>
>
>
>> On 9/24/2014 7:38 AM, M -dot- Vina-Baltsas -at- mindray -dot- com wrote:
>> In general, do you find it easier to write user materials or to edit
>> someone else's work?
>
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as RHearn -at- cucbc -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
>
> Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
> This email and any attachments are strictly confidential, may be privileged, and are intended only for the use of the person(s) named above. Any other person is strictly prohibited from disclosing, distributing, copying or using it. If you are not the intended recipient (or are not receiving this communication on behalf of the intended recipient), please notify the sender immediately by return email or telephone call, and securely destroy this communication. Thank you.
>
> Please reply to this message with "Unsubscribe" or "Unsubscribe All" in the subject line to unsubscribe from this mailing list or from all commercial electronic messages from Central 1.
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as raphaelworkman -at- comcast -dot- net -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
>
> Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
