Tech Writing

classic Classic list List threaded Threaded
26 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Tech Writing

Edward R Cole
Deja Vu:

My first job after graduating college was for Hughes Aircraft Tech
Manuals.  It was almost the end of my career.  But fortunately I was
laid-off in the great engineering purge of spring 1971.  For years a
recurring nightmare was that I was back working at "TM".

I actually did learn a little about writing procedures that was a
help many years later.  I mostly wrote fault-isolation trees and
procedures.  Hughes was fond of handing you a schematic with no title
and no idea of what the function was, and asking for a
troubleshooting procedure.  I pity the poor swabs that had to read
and follow them.  I did once hear back the they took the manual and
tore out the schematics and tossed the rest of the manual.

I was lucky - I got canned.  That led to a job in microwave
engineering with NASA.  Ten years later I walked out of that career
and moved to Alaska without a job, lived in a bare cabin in the
woods, bought some sled dogs, and loved it...never looked back.  Ten
years of that and I got back into the working world, for the last 20-years.

73, Ed - KL7UW

On 6/25/2011 8:16 AM, Tony Estep wrote:

 > Ah, I was once a manual writer. I ran out of money while going to college
 > and took a job writing manuals for a small engineering firm that made
 > transistor testers for Texas Instruments. Later, after I went back and
 > finished school, I was looking for a job and applied at a big electronics
 > company in St. Louis. The guy who interviewed me informed me that most of
 > the applicants had submitted writing samples that were unintelligible, and
 > the few whose writing passed muster couldn't figure out how the equipment
 > worked, so they didn't know what to say. He unrolled a huge, blue-line,
 > hand-drawn schematic and pointed to one of the stages. "What's that?" he
 > demanded. "Schmitt trigger," sez I. Whereupon he jumped up and began
 > gleefully pumping my hand. "Hooray!"
 >
 > But after I got home and thought about it, I realized that the last thing in
 > the world I wanted to do was to write those manuals, and I wound up going in
 > a completely opposite direction.
 >
 > Tony KT0NY



73, Ed - KL7UW, WD2XSH/45
======================================
BP40IQ   500 KHz - 10-GHz   www.kl7uw.com
EME: 50-1.1kw?, 144-1.4kw, 432-100w, 1296-60w, 3400-?
DUBUS Magazine USA Rep [hidden email]
======================================

______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

AC7AC
CONTENTS DELETED
The author has deleted this message.
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

Jim Brown-10
On 6/29/2011 8:23 AM, Ron D'Eau Claire wrote:
> The best writing always comes from personal experience

Yes, and MOST IMPORTANT -- any good writing must TELL A STORY in
language that the reader understands.  If it doesn't do that, it won't
be effective.

73, Jim K9YC
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Mel
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

Mel
I agree with one other element, the story must be at the level of the intended
reader.

Mel, K6KBE




________________________________
From: Jim Brown <[hidden email]>
To: [hidden email]
Sent: Wed, June 29, 2011 11:09:15 AM
Subject: Re: [Elecraft] Tech Writing

On 6/29/2011 8:23 AM, Ron D'Eau Claire wrote:
> The best writing always comes from personal experience

Yes, and MOST IMPORTANT -- any good writing must TELL A STORY in
language that the reader understands.  If it doesn't do that, it won't
be effective.

73, Jim K9YC
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

Joe Subich, W4TV-4

The problem is that there are so many who never bother to ready the
manuals these days ... and even more than can't read anything above
the level of a "graphic novel" (a.k.a. comic book).  It is nearly
impossible to tell a technical story under those conditions.

73,

    ... Joe, W4TV


On 6/29/2011 5:08 PM, Mel Farrer wrote:

> I agree with one other element, the story must be at the level of the intended
> reader.
>
> Mel, K6KBE
>
>
>
>
> ________________________________
> From: Jim Brown<[hidden email]>
> To: [hidden email]
> Sent: Wed, June 29, 2011 11:09:15 AM
> Subject: Re: [Elecraft] Tech Writing
>
> On 6/29/2011 8:23 AM, Ron D'Eau Claire wrote:
>> The best writing always comes from personal experience
>
> Yes, and MOST IMPORTANT -- any good writing must TELL A STORY in
> language that the reader understands.  If it doesn't do that, it won't
> be effective.
>
> 73, Jim K9YC
> ______________________________________________________________
> Elecraft mailing list
> Home: http://mailman.qth.net/mailman/listinfo/elecraft
> Help: http://mailman.qth.net/mmfaq.htm
> Post: mailto:[hidden email]
>
> This list hosted by: http://www.qsl.net
> Please help support this email list: http://www.qsl.net/donate.html
> ______________________________________________________________
> Elecraft mailing list
> Home: http://mailman.qth.net/mailman/listinfo/elecraft
> Help: http://mailman.qth.net/mmfaq.htm
> Post: mailto:[hidden email]
>
> This list hosted by: http://www.qsl.net
> Please help support this email list: http://www.qsl.net/donate.html
>
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

David Honey
In reply to this post by Mel
Absolutely Mel. One of the skills is getting engineers to put themselves
in the shoes of users and put aside much of the technical detail they
know so intimately and tell a story without assuming the reader is an
equal expert in the subject matter. In the software industry, it can be
quite hard finding people who are both good designers and communicators.

73 de David M0DHO

On 2011-06-29 22:08, Mel Farrer wrote:
> I agree with one other element, the story must be at the level of the intended
> reader.
>
> Mel, K6KBE

______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

Jack Chomley
In reply to this post by Joe Subich, W4TV-4
Just like the user manual comic for the M16 Armalite, some 40 years ago :-)

73,

Jack VK4JRC

On Thu, Jun 30, 2011 at 7:43 AM, Joe Subich, W4TV <[hidden email]> wrote:

>
> The problem is that there are so many who never bother to ready the
> manuals these days ... and even more than can't read anything above
> the level of a "graphic novel" (a.k.a. comic book).  It is nearly
> impossible to tell a technical story under those conditions.
>
> 73,
>
>    ... Joe, W4TV
>
>
>
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Mel
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

Mel
In reply to this post by Joe Subich, W4TV-4
You just described the level of education, ability to read and write of the
average HS graduate the schools are putting out.  Pitiful isn't it?

Mel, K6KBE




________________________________
From: "Joe Subich, W4TV" <[hidden email]>
To: Mel Farrer <[hidden email]>
Cc: [hidden email]; [hidden email]
Sent: Wed, June 29, 2011 2:43:23 PM
Subject: Re: [Elecraft] Tech Writing


The problem is that there are so many who never bother to ready the
manuals these days ... and even more than can't read anything above
the level of a "graphic novel" (a.k.a. comic book).  It is nearly
impossible to tell a technical story under those conditions.

73,

    ... Joe, W4TV


On 6/29/2011 5:08 PM, Mel Farrer wrote:

> I agree with one other element, the story must be at the level of the intended
> reader.
>
> Mel, K6KBE
>
>
>
>
> ________________________________
> From: Jim Brown<[hidden email]>
> To: [hidden email]
> Sent: Wed, June 29, 2011 11:09:15 AM
> Subject: Re: [Elecraft] Tech Writing
>
> On 6/29/2011 8:23 AM, Ron D'Eau Claire wrote:
>> The best writing always comes from personal experience
>
> Yes, and MOST IMPORTANT -- any good writing must TELL A STORY in
> language that the reader understands.  If it doesn't do that, it won't
> be effective.
>
> 73, Jim K9YC
> ______________________________________________________________
> Elecraft mailing list
> Home: http://mailman.qth.net/mailman/listinfo/elecraft
> Help: http://mailman.qth.net/mmfaq.htm
> Post: mailto:[hidden email]
>
> This list hosted by: http://www.qsl.net
> Please help support this email list: http://www.qsl.net/donate.html
> ______________________________________________________________
> Elecraft mailing list
> Home: http://mailman.qth.net/mailman/listinfo/elecraft
> Help: http://mailman.qth.net/mmfaq.htm
> Post: mailto:[hidden email]
>
> This list hosted by: http://www.qsl.net
> Please help support this email list: http://www.qsl.net/donate.html
>
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Mel
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

Mel
In reply to this post by David Honey
One of the greatest finds I made, years ago, was come across engineering books
written prior to WWII.  They don't assume "anything" and while it takes longer
to get through a point, once there, education has been accomplished.  


Mel, K6KBE




________________________________
From: David Honey <[hidden email]>
To: [hidden email]
Sent: Wed, June 29, 2011 2:43:48 PM
Subject: Re: [Elecraft] Tech Writing

Absolutely Mel. One of the skills is getting engineers to put themselves
in the shoes of users and put aside much of the technical detail they
know so intimately and tell a story without assuming the reader is an
equal expert in the subject matter. In the software industry, it can be
quite hard finding people who are both good designers and communicators.

73 de David M0DHO

On 2011-06-29 22:08, Mel Farrer wrote:
> I agree with one other element, the story must be at the level of the intended
> reader.
>
> Mel, K6KBE

______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Mel
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

Mel
In reply to this post by Jack Chomley
Last thought on this.  While in the manufacturing business years ago at KLM, we
had complaints about the assembly instructions.  From that point on, the
receptionist had a new job title.  "Assembly instruction manual tester".  When
the manual got to the level where she could put the antenna together
successfully, we shipped it.  Know thy user.

Mel, K6KBE





________________________________
From: Jack Chomley <[hidden email]>
To: "Joe Subich, W4TV" <[hidden email]>
Cc: [hidden email]
Sent: Wed, June 29, 2011 2:49:30 PM
Subject: Re: [Elecraft] Tech Writing

Just like the user manual comic for the M16 Armalite, some 40 years ago :-)

73,

Jack VK4JRC

On Thu, Jun 30, 2011 at 7:43 AM, Joe Subich, W4TV <[hidden email]> wrote:

>
> The problem is that there are so many who never bother to ready the
> manuals these days ... and even more than can't read anything above
> the level of a "graphic novel" (a.k.a. comic book).  It is nearly
> impossible to tell a technical story under those conditions.
>
> 73,
>
>    ... Joe, W4TV
>
>
>
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

Mike Reublin
In reply to this post by Joe Subich, W4TV-4
At first glance I thought "The problem is that there are so many who never bother to
ready the manuals these days" was a typo. Then I realized it is true. A well prepared
manual is a joy!

73, Mike NF4L

  On 6/29/2011 5:43 PM, Joe Subich, W4TV wrote:

> The problem is that there are so many who never bother to ready the
> manuals these days ... and even more than can't read anything above
> the level of a "graphic novel" (a.k.a. comic book).  It is nearly
> impossible to tell a technical story under those conditions.
>
> 73,
>
>      ... Joe, W4TV
>
>
> On 6/29/2011 5:08 PM, Mel Farrer wrote:
>> I agree with one other element, the story must be at the level of the intended
>> reader.
>>
>> Mel, K6KBE
>>
>>
>>
>>
>> ________________________________
>> From: Jim Brown<[hidden email]>
>> To: [hidden email]
>> Sent: Wed, June 29, 2011 11:09:15 AM
>> Subject: Re: [Elecraft] Tech Writing
>>
>> On 6/29/2011 8:23 AM, Ron D'Eau Claire wrote:
>>> The best writing always comes from personal experience
>> Yes, and MOST IMPORTANT -- any good writing must TELL A STORY in
>> language that the reader understands.  If it doesn't do that, it won't
>> be effective.
>>
>> 73, Jim K9YC
>> ______________________________________________________________
>> Elecraft mailing list
>> Home: http://mailman.qth.net/mailman/listinfo/elecraft
>> Help: http://mailman.qth.net/mmfaq.htm
>> Post: mailto:[hidden email]
>>
>> This list hosted by: http://www.qsl.net
>> Please help support this email list: http://www.qsl.net/donate.html
>> ______________________________________________________________
>> Elecraft mailing list
>> Home: http://mailman.qth.net/mailman/listinfo/elecraft
>> Help: http://mailman.qth.net/mmfaq.htm
>> Post: mailto:[hidden email]
>>
>> This list hosted by: http://www.qsl.net
>> Please help support this email list: http://www.qsl.net/donate.html
>>
> ______________________________________________________________
> Elecraft mailing list
> Home: http://mailman.qth.net/mailman/listinfo/elecraft
> Help: http://mailman.qth.net/mmfaq.htm
> Post: mailto:[hidden email]
>
> This list hosted by: http://www.qsl.net
> Please help support this email list: http://www.qsl.net/donate.html
>


______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

Joe Subich, W4TV-4

> At first glance I thought "The problem is that there are so many who
 > never bother to ready the manuals these days" was a typo.

Actually, it was a typo.  While there may be those who don't care to
prepare a quality manual, there are far more instances of users who
simply don't care to even attempt to read/understand the manual.

73,

    ... Joe, W4TV


On 6/29/2011 6:14 PM, Mike wrote:

> At first glance I thought "The problem is that there are so many who never bother to
> ready the manuals these days" was a typo. Then I realized it is true. A well prepared
> manual is a joy!
>
> 73, Mike NF4L
>
>    On 6/29/2011 5:43 PM, Joe Subich, W4TV wrote:
>> The problem is that there are so many who never bother to ready the
>> manuals these days ... and even more than can't read anything above
>> the level of a "graphic novel" (a.k.a. comic book).  It is nearly
>> impossible to tell a technical story under those conditions.
>>
>> 73,
>>
>>       ... Joe, W4TV
>>
>>
>> On 6/29/2011 5:08 PM, Mel Farrer wrote:
>>> I agree with one other element, the story must be at the level of the intended
>>> reader.
>>>
>>> Mel, K6KBE
>>>
>>>
>>>
>>>
>>> ________________________________
>>> From: Jim Brown<[hidden email]>
>>> To: [hidden email]
>>> Sent: Wed, June 29, 2011 11:09:15 AM
>>> Subject: Re: [Elecraft] Tech Writing
>>>
>>> On 6/29/2011 8:23 AM, Ron D'Eau Claire wrote:
>>>> The best writing always comes from personal experience
>>> Yes, and MOST IMPORTANT -- any good writing must TELL A STORY in
>>> language that the reader understands.  If it doesn't do that, it won't
>>> be effective.
>>>
>>> 73, Jim K9YC
>>> ______________________________________________________________
>>> Elecraft mailing list
>>> Home: http://mailman.qth.net/mailman/listinfo/elecraft
>>> Help: http://mailman.qth.net/mmfaq.htm
>>> Post: mailto:[hidden email]
>>>
>>> This list hosted by: http://www.qsl.net
>>> Please help support this email list: http://www.qsl.net/donate.html
>>> ______________________________________________________________
>>> Elecraft mailing list
>>> Home: http://mailman.qth.net/mailman/listinfo/elecraft
>>> Help: http://mailman.qth.net/mmfaq.htm
>>> Post: mailto:[hidden email]
>>>
>>> This list hosted by: http://www.qsl.net
>>> Please help support this email list: http://www.qsl.net/donate.html
>>>
>> ______________________________________________________________
>> Elecraft mailing list
>> Home: http://mailman.qth.net/mailman/listinfo/elecraft
>> Help: http://mailman.qth.net/mmfaq.htm
>> Post: mailto:[hidden email]
>>
>> This list hosted by: http://www.qsl.net
>> Please help support this email list: http://www.qsl.net/donate.html
>>
>
>
> ______________________________________________________________
> Elecraft mailing list
> Home: http://mailman.qth.net/mailman/listinfo/elecraft
> Help: http://mailman.qth.net/mmfaq.htm
> Post: mailto:[hidden email]
>
> This list hosted by: http://www.qsl.net
> Please help support this email list: http://www.qsl.net/donate.html
>
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Writing

k6rb
In reply to this post by Jim Brown-10
It's not just "tech" writing, but writing in general. I made a (very good)
living as a writer (6 books published, many articles in print) since 1977.
And, the world has changed so much since then. Plus, it's pervasive. I
can't begin to tell you how many CEOs never get past the "executive
summary" in a whitepaper. After so many years of working at all levels in
the corporate world, I'm convinced that a large number of CEOs have
attention deficit disorder (ADD), and I'm serious!

The young folks, nowadays, get their news from streaming video media. At
some point, reading will become a lost art. Perhaps it already has. I'm
64, working full time, and at last count I read 66 books since a year ago,
May. Maybe I'm just old fashioned :-).

73,
Rob K6RB

______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Tech Writing - reading the manual

Johnny Siu
In reply to this post by Joe Subich, W4TV-4
Hello Joe,
 
Your observation is correct.  While many hams blame the manual of whatever radio is poorly written, they in fact simply do not border to read the manual.
 
There is even a test about 'how quick you can operate a radio without reading the manual'.
 
English is not my native language and radio is not my profession.  The only way for me to learn radio technology is mostly via reading the manuals thoroughly.  Manuals of radio gears are now becoming my toilet readers (excuse for my indecent words!).  I have the habit of reading the manuals many times.
 
I ordered the KE7X K3 user guide.  No doubt, it is well written and worth the money.  However, if one can thoroughly read all the related manuals produced by Elecraft (or even email exchanges in this reflector), he actually doesn't quite need this user guide.  I do not have a single intention to damage the sales of the KE7X user guide but just simply express what I feel after reading it.

TNX & 73,


Johnny VR2XMC

從︰ "Joe Subich, W4TV" <[hidden email]>
收件人︰ [hidden email]
副本(CC)︰ [hidden email]
傳送日期︰ 2011年06月30日 (週四) 6:52 AM
主題︰ Re: [Elecraft] Tech Writing


> At first glance I thought "The problem is that there are so many who
> never bother to ready the manuals these days" was a typo.

Actually, it was a typo.  While there may be those who don't care to
prepare a quality manual, there are far more instances of users who
simply don't care to even attempt to read/understand the manual.

73,

    ... Joe, W4TV


On 6/29/2011 6:14 PM, Mike wrote:

> At first glance I thought "The problem is that there are so many who never bother to
> ready the manuals these days" was a typo. Then I realized it is true. A well prepared
> manual is a joy!
>
> 73, Mike NF4L
>
>    On 6/29/2011 5:43 PM, Joe Subich, W4TV wrote:
>> The problem is that there are so many who never bother to ready the
>> manuals these days ... and even more than can't read anything above
>> the level of a "graphic novel" (a.k.a. comic book).  It is nearly
>> impossible to tell a technical story under those conditions.
>>
>> 73,
>>
>>       ... Joe, W4TV
>>
>>
>> On 6/29/2011 5:08 PM, Mel Farrer wrote:
>>> I agree with one other element, the story must be at the level of the intended
>>> reader.
>>>
>>> Mel, K6KBE
>>>
>>>
>>>
>>>
>>> ________________________________
>>> From: Jim Brown<[hidden email]>
>>> To: [hidden email]
>>> Sent: Wed, June 29, 2011 11:09:15 AM
>>> Subject: Re: [Elecraft] Tech Writing
>>>
>>> On 6/29/2011 8:23 AM, Ron D'Eau Claire wrote:
>>>> The best writing always comes from personal experience
>>> Yes, and MOST IMPORTANT -- any good writing must TELL A STORY in
>>> language that the reader understands.  If it doesn't do that, it won't
>>> be effective.
>>>
>>> 73, Jim K9YC
>>> ______________________________________________________________
>>> Elecraft mailing list
>>> Home: http://mailman.qth.net/mailman/listinfo/elecraft
>>> Help: http://mailman.qth.net/mmfaq.htm
>>> Post: mailto:[hidden email]
>>>
>>> This list hosted by: http://www.qsl.net
>>> Please help support this email list: http://www.qsl.net/donate.html
>>> ______________________________________________________________
>>> Elecraft mailing list
>>> Home: http://mailman.qth.net/mailman/listinfo/elecraft
>>> Help: http://mailman.qth.net/mmfaq.htm
>>> Post: mailto:[hidden email]
>>>
>>> This list hosted by: http://www.qsl.net
>>> Please help support this email list: http://www.qsl.net/donate.html
>>>
>> ______________________________________________________________
>> Elecraft mailing list
>> Home: http://mailman.qth.net/mailman/listinfo/elecraft
>> Help: http://mailman.qth.net/mmfaq.htm
>> Post: mailto:[hidden email]
>>
>> This list hosted by: http://www.qsl.net
>> Please help support this email list: http://www.qsl.net/donate.html
>>
>
>
> ______________________________________________________________
> Elecraft mailing list
> Home: http://mailman.qth.net/mailman/listinfo/elecraft
> Help: http://mailman.qth.net/mmfaq.htm
> Post: mailto:[hidden email]
>
> This list hosted by: http://www.qsl.net
> Please help support this email list: http://www.qsl.net/donate.html
>
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing - reading the manual

Tony Estep
There has been a substantial evolutionary change in documentation and
support in technology, one that has put manuals in a much different
relationship to the user than they had a decade ago.

Some tech products come with no manual (e.g. iPhones). There are big hairy
software extravaganzas that come with no manual (e.g. Photoshop). These
products are not necessarily rejected by users. A manual is one way to get
info to the user, but there are other ways: menu captions, tool tips,
on-line help, context-sensitive help files, and (most importantly) a design
that is laid out so that the user can sometimes guess what to do.

 Many products get support through user forums and/or books written by
independent third parties ("VBA Programming for the Total Nitwit"). The K3
enjoys excellent support from both of these sources. When a manufacturer
gets a lot of complaints that people can't understand how to work his
product, he can't hide behind the assertion that his clientele are all
dolts; they probably own other tech products that they can work just fine.
If a program or gadget is hard to understand, it will sell poorly and
acquire a bad reputation; and the converse is true too. The burden is not on
the reader or user. It's on the maker of the product.

Tony KT0NY
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

Jim Brown-10
In reply to this post by Mel
I guess I failed  -- I said "in language that the reader understands."

73, Jim K9YC

On 6/29/2011 2:08 PM, Mel Farrer wrote:

> I agree with one other element, the story must be at the level of the
> intended reader.
>
> Mel, K6KBE
>
> ------------------------------------------------------------------------
> *From:* Jim Brown <[hidden email]>
> *To:* [hidden email]
> *Sent:* Wed, June 29, 2011 11:09:15 AM
> *Subject:* Re: [Elecraft] Tech Writing
>
> On 6/29/2011 8:23 AM, Ron D'Eau Claire wrote:
> > The best writing always comes from personal experience
>
> Yes, and MOST IMPORTANT -- any good writing must TELL A STORY in
> language that the reader understands.  If it doesn't do that, it won't
> be effective.
>
> 73, Jim K9YC

______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

Dave KK7SS
In reply to this post by Edward R Cole

An Operations Manual group I wrote for a US Army Project was rejected with instructions that it was to be written to a Grade 7 education level!
Including pictures, for example, of which way to turn a screwdriver to remove or insert a screw - and which end to use!

I kid you not!

--
Dave G  KK7SS
 Richland, WA
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

John KLim
Dave,

I believe you.

A very good friend of mine once told me anyone can idiot proof anything, but
can they manager proof it?  The basic answer was NO WAY!

73 ES CUL  DE  N3KHK
=============================================
John R. Klim II
ARRL LM, AMSAT LM
10-10:  68135
30MDG:  1820
QSL:  LoTW, Bureau, Direct, eQSL as a courtesy

 

-----Original Message-----
From: [hidden email]
[mailto:[hidden email]] On Behalf Of Dave KK7SS
Sent: Thursday, June 30, 2011 12:34 AM
To: [hidden email]
Subject: Re: [Elecraft] Tech Writing


An Operations Manual group I wrote for a US Army Project was rejected with
instructions that it was to be written to a Grade 7 education level!
Including pictures, for example, of which way to turn a screwdriver to
remove or insert a screw - and which end to use!

I kid you not!

--
Dave G  KK7SS
 Richland, WA
______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html

______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

Phil Kane-2
In reply to this post by Dave KK7SS
On 6/29/2011 9:33 PM, Dave KK7SS wrote:

> An Operations Manual group I wrote for a US Army Project was
> rejected with instructions that it was to be written to a Grade 7
> education level! Including pictures, for example, of which way to
> turn a screwdriver to remove or insert a screw - and which end to
> use!

> I kid you not!

  We laugh about it, but it really is a sad reflection on the
  educational level of allegedly educated/trained people.  I
  spent the latter half of my career mentoring young engineers in
  how to write a reasonably understood report of measurements or
  inspections that they did.

--  73 de K2ASP - Phil Kane
    Elecraft K2/100   s/n 5402

______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
Reply | Threaded
Open this post in threaded view
|

Re: Tech Writing

gdaught6
In reply to this post by John KLim
> A very good friend of mine once told me anyone can idiot proof anything, but
> can they manager proof it?  The basic answer was NO WAY!

Always keep Dilbert's 'pointy-haired boss' in mind.

I was told by someone 'It is impossible to make anything foolproof, because fools are
often terribly clever.'

73,

George T Daughters, K6GT
CU in the California QSO Party (CQP)
October 1-2, 2011


______________________________________________________________
Elecraft mailing list
Home: http://mailman.qth.net/mailman/listinfo/elecraft
Help: http://mailman.qth.net/mmfaq.htm
Post: mailto:[hidden email]

This list hosted by: http://www.qsl.net
Please help support this email list: http://www.qsl.net/donate.html
12