K3 docs ... clarification

[John Ragle]

As someone said, this is a long thread. (Some threads are too long
before they start.) I just wanted to clarify/correct an impression that
my previous carelessness in expression may have made.

There is a substantial difference between a "computer-generated" index
(fie on that!) and an index generated by a human who is using the
collation tool ("index generator") in a good word processor. I was
referring to the latter.

The most brilliant monograph is worthless without a high-quality index.
Of course both a written index and a "search" tool in (e.g.) Acrobat
lead to many false hits. Authors should put as much care into their
index as they do in the best parts of their texts. IMHO.

John Ragle -- W1ZI
______________________________________________________________
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

[wayne burdick]

The present index was not machine-generated. It was derived from a  
concordance file that was compiled by hand by our tech writer, Ron  
(AC7AC). I add new entries to the index as they're added to the  
manual, and since I maintain this manual personally, you can blame me  
for any lack of entries.

Every time I revise the manual I try to improve it based on user  
feedback. Keep those cards 'n' letters coming.

73,
Wayne
N6KR

On Dec 7, 2010, at 11:36 AM, John Ragle wrote:

> As someone said, this is a long thread. (Some threads are too long
> before they start.) I just wanted to clarify/correct an impression  
> that
> my previous carelessness in expression may have made.
>
> There is a substantial difference between a "computer-generated" index
> (fie on that!) and an index generated by a human who is using the
> collation tool ("index generator") in a good word processor. I was
> referring to the latter.
>
> The most brilliant monograph is worthless without a high-quality  
> index.
> Of course both a written index and a "search" tool in (e.g.) Acrobat
> lead to many false hits. Authors should put as much care into their
> index as they do in the best parts of their texts. IMHO.
>
> John Ragle -- W1ZI

______________________________________________________________
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

[Kok Chen]

The K3 manual, like the FT-1000MP manual, seems to have an index that is ordered by Functions, which is natural for manufacturers and designers but perhaps not so much for users.  The manual is written from the point of view of somebody who already knows how to use the K3.

Someone had suggested an index which contains "subtopics."  I thought that is a great idea.

For example, under an "Antenna" index, you can have sub indexes to everything that has anything to do with antennas, ATU, connectors, buttons that control antenna functions, etc.  

With some books, you will find for example the index for "Rhombic" stating "(see under Antennas)." This way, you can either look for "Rhombics" or look for "Antennas."   Especially useful if you have heard of the term "rhombics" sometime in the murky past but, with a memory like I have, don't really remember the precise name, so you go look under "Antennas."  Not to say the K3 index should include the term Rhombic :-) :-).

For example, if I want to look for information about the RF connectors at the rear panel, I don't need to guess if Elecraft had call it coax connectors, SO-239, BNC, etc.  I just go look under "Antennas" or some such generic term.

The ARRL Handbook leans towards this style.

One thing that I have found very useful in the FT-1000MP manual is that the numbered captions on the front and rear panel diagrams are described in an ordered list containing short paragraphs AND a page number to leads you to the detail description somewhere else.  So, you can jump from the number directly to the short description (to see if it is really what you are looking for) and finally to the main body of the manual.  Very simple steps.

With the K3 manual, the main VFO knob is labeled "22" in the front panel diagram, but to find the description of "22," you need to search like crazy in the following pages: it appears in "The Basics." But how would I know to look for it there if I hadn't written the manual myself? :-)  

OK, so the VFO knob appears later in yet another diagram of the front panel -- but this time there is no number.  So you again have to plow through looking for the reference to "VFOs" but at least finally, you have a reference to the page in the manual where the VFO controls are described in detail.

All that being said, the part I hate most myself is writing documentation.  So I definitely put myself in the category of "do what I say, not what I do" HI HI.  

My documentation for cocoaModem, for example is pretty much along the line of the K3 manual -- function driven.  Then I let the pendulum swing completely in a different direction in the cocoaNEC documentation where I created Tutorials.  E.g., sections that are titled "Creating a New Antenna Model," "Creating a Simple Dipole," "Setting feeds, Frequencies and Radiation pattern parameters," etc.

The excuse I use for the poor manuals for my programs?  They are free :-) :-)

73
Chen, W7AY


______________________________________________________________
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

[k6dgw]

On 12/7/2010 2:40 PM, Kok Chen wrote:
> The K3 manual, like the FT-1000MP manual, seems to have an index that
> is ordered by Functions, which is natural for manufacturers and
> designers but perhaps not so much for users.  The manual is written
> from the point of view of somebody who already knows how to use the
> K3.

A friend, who swears this is true, told me about an attempt to try out a
new instruction manual for some software on one of the admin folks since
he would be the primary user.  The software was on a 5 1/4" floppy [this
occurred a long time ago, if you don't know what a 5 1/4" floppy disk
was skip to the bottom].  The instructions had been made very precise
and followed the principle that each instruction did one and only one
thing so that no confusion could result and nothing could go wrong.  It
went something like:

1.  "Locate the 'SOFTWARE' diskette in the file case on the desk."  User
flips through and finds it.

2.  "Remove the diskette."  User pulls the floppy out of the case,
leaving the sleeve behind.

3.  "Remove the diskette from its cover."  User proceeds to tear the
outer cover off the diskette.

Tech writing is hard, and how one writes depends on who the audience is
and what their situations are.  I'm happy with the technical accuracy of
the K3 manual, and the Index/PDF Search.  It's easily as good as the
better examples I have used, and light years ahead of some.  Admittedly,
I do have to have a reasonable idea of what it is I'm looking for, and
sometimes it takes a couple of tries, it tends to be function oriented.
  So does Google, and the new ARRL Web Site is probably one of the
poorer examples in this regard for me.  So is the N1MM documentation.

What most folks seem to be wanting is, for lack of a better metaphor,
"K3 USAGE for Dummies," focused on K3 usage.  Not every
function/feature/adjustment applies to every one of the multiple uses of
my K3.  Tell me about receiving CW under varying conditions ... I'll
read that.  Since I'm really still a dummy at K3 Usage, I won't write it
[there are other reasons I won't as well, but that's my story and I'm
sticking to it].

73,

Fred K6DGW
- Northern California Contest Club
- CU in the 2011 Cal QSO Party 1-2 Oct 2011
- www.cqp.org

Maybe that wasn't a "metaphor," perhaps a simile?  I can't keep them any
straighter than prepositions and split infinitives.
______________________________________________________________
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