96497 - Remove all Help buttons from Show Example screens for CCK

Status: VERIFIED FIXED

(CCK Graveyard :: CCK-Wizard, defect)

Description

[Sean Cotter]

Help buttons for the Show Example screens aren't necessary. The help files
associated with them frequently provide redundant info (e.g., how to reach the
main CCK screen from which you launched the Show Example screen) or obsolete
info copied from older versions of the manual, creating a maintenance nightmare.

The help buttons on the main CCK screens should remain where they are.

Comment 1

[Barrett Lindstrom]

Updating QA contact to jimmyu for half of the CCK bugs, while Bom-shik is gone.

Comment 2

[Shruti Vasudevan]

According to my opinion most of the help files (75%) in the show example screens 
are useful. If we remove the help files in these show example screens, the user 
has to click on the main help button in the wizard screen. Then, find where the 
information for a particular customization is present. After that he has to 
click on another link to get more information for a particular customization. 

However, if we retain the help file in the show example screens all information 
for that particular customization is clearly available, user need not click on 
any other links.

Note: Once we remove the help files in the show example screens, it will be 
difficult to add them back, if we decide so in future, because there are more 
than 15 files.

Comment 3

[bobj]

I looked at several and I agree they do seem useful.

To address the issue of "obsolete info copied from older versions of the manual,
creating a maintenance nightmare", could the Help buttons just jump to the
appropriate anchor in the local copy of the guide?

But we might want to make these changes for eMojo...

Comment 4

[Sean Cotter]

Since we agreed earlier that the Show Example help buttons should be removed,
none of the help files attached to them have been updated. Given how much I have
to do in the next two weeks, they will not be updated. Many of them contain
obsolete or just plain wrong information.

The strategy I've followed thus far will be apparent in the next build
(preliminary versions of all help and manual files have been checked in). Please
wait and view that build before making a final decision on this issue.

As the new manual makes clear (and will be even clearer once I've incorporated
John's suggestions for the overview section), you need to prepare your files
before running the tool. While the Show Example dumps are useful as a reminder
of what each customization looks like, they are not the appropriate place to
look for file preparation information that you need to have before you run the tool.

As you will see in the next build, each help file includes links to the relevant
"preparing" chapter in the manual. So if you happen to run the tool without
doing your homework first, you can easily get to the relevant material if you're
running the tool (by clicking the main Help button, reading some basic
contextual info, and clicking the links that each Help file provides) or by
simply reading the manual (which now separates out the "preparing" chapters,
each clearly linked from the TOC).

It would certainly be possible to link the Show Example help sections directly
to the relevant manual sections. This would be better, and much easier to
maintain, than duplicating a bunch of material from the manual into all these
little files. However, linking the buttons directly in this way creates a
different maintenance problem. As the tool and documentation continue to change
in future versions, many of those help buttons would have to be rewired. Keeping
links to the manual in the main Help files makes them much easier to maintain.

Finally, I disagree that this information, even if it were absolutely up to date
and single-sourced in the manual itself, is relevant in the context of the Show
Example screens. The Show Example screens are only a reminder. If you quit the
tool to work on your file preparation, they aren't available. I still believe
that the Help buttons in the Show Example screens are redundant and should be
removed, the sooner the better. No matter how they're implemented they create a
maintenance problem with no instructional payoff that makes sense to me.
Remember, last time round nobody on the team even noticed that they were there
until I pointed them out! 

I hope my point of view will become clearer when you play with the main Help
buttons in the next build. Bottom line: If you keep the help buttons, link them
to the relevant manual sections (I can provide the links) and accept the fact
that many of these hard-coded links will have to change with each new release.
Possibly Kristi or I could learn where these links are maintained in the code
and update them ourselves. 

However, my preference remains: cut the fat and get rid of this redundant set of
help buttons completely. The issue is not, "is the information useful?" The
issue is: at what point in the customization process does the user need the
information, and what is the most efficient way of delivering it?

Comment 5

[bobj]

> If you keep the help buttons, link them
> to the relevant manual sections (I can provide the links) and accept the fact
> that many of these hard-coded links will have to change with each new release.

***IF*** we keep them, couldn't we add special "#HELP-blahblah" anchors, so it
would be obvious which are linked by help.  If the anchors get removed from the
guide, then the help link should just go to the top of that chapter.

Comment 6

[Shruti Vasudevan]

As per Sean's email and Bob's comments, will remove all help buttons and 
associated files in CCK show example images. 

Comment 7

[bobj]

> As per Sean's email and Bob's comments,

Below, I pasted the email comments.

Bob's email comments:
=====================
I looked at the new Help content for each CCK screen and it appears to be OK. 
It still requires a user to manually scroll and look for the particular section
associated with a show example image, but usually not too far and the help
pages are not too long.  So I think it's acceptable for eMojo to remove the
Help buttons from the Show Example windows.

But I have yet another (post-eMojo) proposal:

    * Move the show example images into the HTML help files and add an anchor
      tag for each image.
    * Have show examples open up the HTML help files to the appropriate anchor.

There's no reason to keep these related pieces of info in separate places.
And this way, users reading the help would have immediate access to the show
example image, and users looking at the show example images would have
immediate access to the help text.

======================
Sean's email comments:
======================
I agree that the help buttons in the Show Example screens should be eliminated
for this release.

I also agree that Bob's proposal to integrate the Show Example images with
the main Help button files makes sense for future releases.

Comment 8

[Shruti Vasudevan]

Attachment: Removing help button and refernces

Comment 9

[tao]

Comment on attachment 51100 [details] [diff] [review]
Removing help button and refernces

r=tao

Comment 10

[Shruti Vasudevan]

Marking fixed.

Comment 11

[Jimmy Uen]

Verified with CCK build 2001-10-01-09 on Win2K.