Re: Re[2]: What sayest me... on Worthless TC Degrees

[John Posada <jposada01 -at- yahoo -dot- com>]

>      structured so poorly. If the book was arranged
> well, the index 
>      wouldn't be needed.<
>      
>      Your kidding, right?

Only partialy. I do many documents that don't hacve an
index, and I've had someone complain that they
couldn't find something.

>      If you think an index is not needed, I have
> some questions: 
>      
>      - How do you go about discussing or mentioning
> the ABC window in only 
>      one place in the book? 

I don't...but the reason I mention a window is not to
mention a window, but to discuss some feature, and
that window might be the manefestation of the feature,
but a window for window's sake? Nah. i don't care a
rat's=*** about a window...what am I, a developer?
   
>      - Do you discuss the ABC window in relation to
> the other windows in 
>      the book? If so, don't you need an index hit
> for these? 

I might use cross-reference..(see Fig 3 on page 4-4)
      
>      - How do you go about discussing or mentioning
> the XYZ function in 
>      only one place in the book? 

Why do I need an index to discuss a function and what
IS the problem with discussing the same function
twice. I HATE when I have to flip throughout a book
and keep my train of thought. I might mention the same
piece of information 2 or 3 times if it is appropriate
to discuss it at that point each time. 

Why not discuss the function where it is logical to
discuss that function and have the user find that
discussion at that location because it is the logical
place to find that discussion?
      
>      - Do you discuss the XYZ function in relation
> to the other functions 
>      in the book? If so, don't you need an index hit
> for these? 

No, how about a cross-refereence right at the point
where it is appropriate, or yes, I might repeat the
same piece of information if it helps reader
comprehension. 
      
>      - How do you go about cramming EVERYTHING about
> the ABC window in one 
>      place in your book? If it's discussed in two or
> more places, don't you 
>      you need two or more index hits. 

Again, you're placing the priority on the element for
element's sake rather than the purpose of the element.
When I open a book, it isn't to find out everything
about a window. I  may want to perform a function.

2.0   Functions
2.1    Create Files
2.1.1   From Imported Data
2.1.2   From Native Data
2.2    Move Files
2.1.1   Between Directories
2.1.2   Between Computers on a Network

I, as a user, want to move a file from one computer to
another. Sure, it involves a window. But that's
because it involves a window. I don't care if it
involves a command line, a keyboard command, or a
Command Performance for the Queen. Why not logically
bring them to the section of the document describing
function, then show them that window?
      
>      - How do you go about cramming EVERYTHING about
> the XYZ function in 
>      one place in your book? If it's discussed in

With or without an index, you place what is
appropriate about "something", where it is appropriate
to position it. An index doesn't make anything right
or wrong...it just makes finding something in an
illogical place easier to find.

>      - Does your book have any cross references? If
> yes, don't you need an 
>      index hit for each occurrence .

No, why do I need an index for a cross-reference. A
cross-reference is a cross reference.
      
>      So you don't want to help the user navigate
> your book? Why not 

I want them to be able to naturaly navigate the book
by structuring it well, not pouring a book full of
facts between  covers, then develop external pointers.

>      eliminate the TOC also. After all, if the book
> is well-organized, the 

I use TOCs alot...but again, don't combine the
function of a TOC with an index.

>      the book and to see where information is
> discussed. But then maybe 
>      headers and footers aren't needed either

no, I like headers and footers. I may even use
dictionary style headers.

Don't extend my belief that indexes are a crutch
denote that other elements are also. I'm speaking
specificaly about indexes.

>      Wow. What a concept. This job gets easier
> everyday. <more heavy 
>      sarcasm> 

Sometimes it is easier than we'd like others to
believe, but then we couldn't request the bucks.

On the other hand, it's hard to create documentation
that is structured the way we think, rather than
according to some prehistoric set of rules, because
that's the way documentation was always created and
what's good for grandma is good enough for me,
dagnabbit. 

=====
John Posada, Merck Research Laboratories
Sr Technical Writer, WinHelp and html
(work) john_posada -at- merck -dot- com - 732-594-0873
(pers) jposada01 -at- yahoo -dot- com - 732-291-7811
Beer is proof that God loves us and wants us to be happy.
     Benjamin Franklin

__________________________________________________
Do You Yahoo!?
Talk to your friends online with Yahoo! Messenger.
http://im.yahoo.com