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 should clarify that I do not simply cut/paste what the developer gives me. I do fill in the blanks.
-----Original Message-----
From: techwr-l-bounces+phanson=quintrex -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+phanson=quintrex -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Paul Hanson
Sent: Friday, July 10, 2009 5:02 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: RE: Appropriate -- so inappropriate!
I have it so good. You all should be jealous of me.
When a project or system change comes to QA, our developers are required to give QA a document. The document explains what their changes were to the system. There is a wide range of quality in these docs. Some developers include worthless statements like "Created new program to add new whizbangs" without explaining what and why the user would want to set up a whizbang in the first place. Other developers create Word docs with screen captures of before and after. Some have *pages* of painstaking detail about what they changed and how it affects the program they changed. One developer always includes before and after screen shots of any UI changes he makes. Still other developers go through and show what the program did before their change - including if the program blew up - and then even more pages explain how the same scenario, with the changed program, processes correctly without blowing up.
I am unashamed to say that I take what the SMEs give me and make it look pretty.
That said, I think I'd separate the statement below as follows:
They typically don't care to understand the products and technology they're documenting <-- not me.
preferring to simply edit and <make "look pretty" the information they get from SMEs and other sources. <-- yes, because the source material I get is often totally awesome!
And they often defend their ignorance by <saying it makes them more in tune with novice users. <-- not me
At my first TWing job, my manager criticized me for lack of industry knowledge in one of my performance reviews. She knew that in addition to TWing, I was writing music reviews, which I would show her when the local newspaper published a new one. She told me that when I wrote about music, there was passion and a complete understanding of the CD I was reviewing. I demonstrated that I could pick and choose what was important and what was unimportant. I had a mastery of the subject. That same mastery, she told me, is what I should strive for in my TWing. Get all the possible information you can get and then filter what is and is not needed.
I know these ideas are not new but I think it bears repeating for anyone, new to the industry or not.
<snip>
They typically don't care to understand the products and technology they're documenting, preferring to simply edit and <make "look pretty" the information they get from SMEs and other sources. And they often defend their ignorance by <saying it makes them more in tune with novice users.
<snip>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices. http://www.doctohelp.com/SuperPages/Webcasts/
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as PHanson -at- quintrex -dot- com -dot-
Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices. http://www.doctohelp.com/SuperPages/Webcasts/
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
