RE: Appropriate -- so inappropriate!

Subject: RE: Appropriate -- so inappropriate!
From: Paul Hanson <phanson -at- Quintrex -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 10 Jul 2009 17:01:35 -0500

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.

Paul

-----Original Message-----
From: Kathleen MacDowell

<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 archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


Follow-Ups:

References:
RE: Appropriate -- so inappropriate!: From: Combs, Richard
Re: Appropriate -- so inappropriate!: From: Kathleen MacDowell
RE: Appropriate -- so inappropriate!: From: Combs, Richard
Re: Appropriate -- so inappropriate!: From: Kathleen MacDowell

Previous by Author: RE: PDFs as online help?
Next by Author: RE: Appropriate -- so inappropriate!
Previous by Thread: Re: Appropriate -- so inappropriate!
Next by Thread: RE: Appropriate -- so inappropriate!


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads