Need for ideas: "Here's all the info" vs. "Keep it short"

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

Post Reply
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Need for ideas: "Here's all the info" vs. "Keep it short"

Unread post by Dave Gehman »

Any and all advice very welcome.

Scenario:
WebHelp format.
Technical (engineering) software that has some arcane concepts that need many words and many pictures for explanation.

One segment of the docs is a simple and quick step-by-step self-training curriculum. Or, at least it's meant to be simple and quick. Unfortunately, it introduces/draws on (and should offer to explain) the wordy concepts.

How best can we include the concepts in the simple segment? Or, rather, how best can we include the explanations in a non-intrusive way?

1. We can use toggles, but do they work in all browsers? I have to revisit H+M documentation on these as I remember some sort of gotcha -- I just don't remember what it was.

2. We can use links - click on a word, go to a long explanation in the Concepts segment.

But then it's important to get the user back to the simple step-by-step -- exactly at the point when they left to dig into the Concept...

3. Use anchors and link to them at the end of the relevant Concept discussion?

Will those anchors appear in the search and index tabs of the WebHelp? They wouldn't have much use there. Is there a way to make anchors "private" -- that is, keep them from joining the search or the index?

4. -- ? any ideas?
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Need for ideas: "Here's all the info" vs. "Keep it short

Unread post by Martin Wynne »

Dave Gehman wrote:But then it's important to get the user back to the simple step-by-step -- exactly at the point when they left to dig into the Concept...
Hi Dave,

That's what the "Back" button in the browser does. Not the one in the Help, the one above that in the browser. You just need to tell your users to click it.

Alternatively, you can open your Detailed explanation in a separate browser tab. Then the Simple stuff is still in the previous tab exactly where they left it. All topic links in H&M have an option to open them in a new "window" -- which nowadays means a new tab, the wording on the dialog needs updating.

You might like to look at FBR interactive video for the simple step-by-step. You can include pauses in the video with buttons clickable into the detailed Help. If you host it on Blueberry's own media server (free for FBR users, easy upload straight from the FBR editor), the interactive stuff works even for MP4 video, no need for Flash. See: https://www.flashbackrecorder.com/

What's strange is that Blueberry make little mention of the interactive functions on their web site, but it is far and away the most valuable feature.

I'm in the same boat as you -- explaining detailed technical stuff to users who mostly haven't a clue at the start.

regards,

Martin.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Need for ideas: "Here's all the info" vs. "Keep it short

Unread post by Dave Gehman »

Thanks, Martin - hadn't thought of the new tab option. That's probably the best.

Much appreciated.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Need for ideas: "Here's all the info" vs. "Keep it short

Unread post by Dave Gehman »

Ah - a couple of issues.

The browser Back works sometimes. Most instances seem to go back to the top of the original topic... but it's academic.

Unfortunately, my link dialog has only two options - "(Same Window)" and "Main." Selecting either one doesn't result in the creation of a new tab (in Chrome, anyway)...

EDIT: oops - I didn't realize that I had to select "Internet Link" rather than "Topic Link" Any idea if I can have both? We'll want other publishing results besides WebHelp, proabably PDF or Word.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Need for ideas: "Here's all the info" vs. "Keep it short

Unread post by Martin Wynne »

Dave Gehman wrote:The browser Back works sometimes. Most instances seem to go back to the top of the original topic... but it's academic.
Hi Dave,

That might depend on which skin you are using and which browser. It always works for me in Firefox and Edge.
I didn't realize that I had to select "Internet Link" rather than "Topic Link" Any idea if I can have both? We'll want other publishing results besides WebHelp, proabably PDF or Word.
Sorry I didn't make that clear. Yes you can have both, just put the two links inside conditional text tags. They need a slightly different URL format of course.

regards,

Martin.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Need for ideas: "Here's all the info" vs. "Keep it short

Unread post by Dave Gehman »

Well, the new tab idea is most tantalizing, but I can't get it to work in WebHelp.

I'm not finding a switch in configuration or Publishing to trigger the calling up of a new window/tab for links, and the options in the HTML link dialog don't include "New Window."

It looks as though we might have to edit the relevant <a href.... /a> to add the necessary 'target = "_blank"'
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Need for ideas: "Here's all the info" vs. "Keep it short

Unread post by Martin Wynne »

Dave Gehman wrote:Well, the new tab idea is most tantalizing, but I can't get it to work in WebHelp.
Hi Dave,

This is what H&M puts in the internet links for me:

Code: Select all

<a href="http://www.wyreforest.gov.uk" target="_blank" rel="nofollow" class="weblink">
All working fine here. Which skin are you using, if any? I tend not to use one nowadays, I find it easier to edit the original H&M templates rather than configure a separate skin.

regards,

Martin.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Need for ideas: "Here's all the info" vs. "Keep it short

Unread post by Dave Gehman »

Once again, many thanks for taking the time to help.

First, is your quoted code drawn from WebHelp output?

If so, which skin?

EDIT: missed the part in your message where you said you didn't use a skin. How do you output WebHelp without a skin?

My skin: all I'm using right now is a very basic one (and that will change - it's for reasons too complex to cover right now). Two Frames Classic Skin Silver.


Second, I simply don't have any place or switch that specifies that I want a new window / new tab. Where do you see that switch or choice? On the H+M Link dialog and if so, which tab?

Mark me, increasingly confused...
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Need for ideas: "Here's all the info" vs. "Keep it short

Unread post by Martin Wynne »

Hi Dave,

It's here. Edit the link:
hm_link.png
missed the part in your message where you said you didn't use a skin. How do you output WebHelp without a skin?
Click "remove skin" at the very bottom of the "open skin" panel.

Written in haste as I have to go out.

cheers,

Martin.
You do not have the required permissions to view the files attached to this post.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Need for ideas: "Here's all the info" vs. "Keep it short

Unread post by Dave Gehman »

Ah, I see.

[I know you're busy, and I'm shamelessly dragging this on, but maybe, if you still have patience left, we can continue tomorrow.]

The stopper, or at least a major slower-downer, in this case is that the Internet link has to be in the form of a URL.

I very much hanker after the "Target" selection pane in the Topic Link form, where I can click on a topic and (if any) an anchor within. Do you automate the typing-in of the full URL? Or do you put each one in manually?
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Need for ideas: "Here's all the info" vs. "Keep it short

Unread post by Martin Wynne »

Dave Gehman wrote:Do you automate the typing-in of the full URL? Or do you put each one in manually?
Hi Dave,

I have my last publish open in Edge (it has to be Edge for me because I use PHP files, and Edge is the only browser which will render local PHP files).

On my topic page template in H&M I have a link to the current page at the bottom of every topic page:
hm_page_link.png
So to create a new link from another topic I simply right-click on that and copy the URL, and then paste it into the link dialog. If you want to keep it all relative you can delete the domain part of the URL, but I don't bother -- I'm not planning to change my domain or Help folder any time soon, and if I do I can use Notepad++ to edit all the XML files.

Adding an anchor just means adding #anchor_name to the URL, although I seldom use anchors for external page links. Jumping into the middle of a new page is confusing to many users. It's better to create separate shorter topics. You can always combine them into a longer reference page as snippets if you want to.

cheers,

Martin.
You do not have the required permissions to view the files attached to this post.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: Need for ideas: "Here's all the info" vs. "Keep it short

Unread post by Dave Gehman »

As always, thanks, Martin.

It looks as though I'll have to bite the bullet and manually enter URL-based links to all the applicable areas in the topics. That's going to amount to upwards of 8 manual links per topic on 30+ topics. Plus debugging, thanks to my fat-fingered typos. :(

Then re-doing them with every revision. :cry:

I really wish there were a way to generate a new-tab type HTML link in WebHelp by simply clicking on the target, similar to the clickable list when setting up a Topic Link.
User avatar
Martin Wynne
Posts: 2656
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Need for ideas: "Here's all the info" vs. "Keep it short

Unread post by Martin Wynne »

Dave Gehman wrote:It looks as though I'll have to bite the bullet and manually enter URL-based links to all the applicable areas in the topics. That's going to amount to upwards of 8 manual links per topic on 30+ topics. Plus debugging, thanks to my fat-fingered typos. :(
Hi Dave,

You could search and replace them all in one go using Notepad++ in the XML files.

That way you could use the conventional topic links while writing your Help.

You could add the conditional flags at the same time, all in one go. I often write Windows utilities to do stuff like this.

Tim will be along shortly to tell you not to use external HTML links for topic links. :)

cheers,

Martin.
Post Reply