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

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

Unread postby Dave Gehman » Mon Feb 12, 2018 1:30 pm

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?
Dave Gehman
 
Posts: 232
Joined: Sat Sep 23, 2017 9:05 pm

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

Unread postby Martin Wynne » Mon Feb 12, 2018 4:05 pm

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.
User avatar
Martin Wynne
 
Posts: 2358
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 postby Dave Gehman » Mon Feb 12, 2018 4:12 pm

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

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

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

Unread postby Dave Gehman » Mon Feb 12, 2018 4:25 pm

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.
Dave Gehman
 
Posts: 232
Joined: Sat Sep 23, 2017 9:05 pm

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

Unread postby Martin Wynne » Mon Feb 12, 2018 5:15 pm

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.
User avatar
Martin Wynne
 
Posts: 2358
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 postby Dave Gehman » Mon Feb 12, 2018 5:34 pm

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"'
Dave Gehman
 
Posts: 232
Joined: Sat Sep 23, 2017 9:05 pm

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

Unread postby Martin Wynne » Mon Feb 12, 2018 5:59 pm

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.
User avatar
Martin Wynne
 
Posts: 2358
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 postby Dave Gehman » Mon Feb 12, 2018 7:34 pm

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...
Dave Gehman
 
Posts: 232
Joined: Sat Sep 23, 2017 9:05 pm

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

Unread postby Martin Wynne » Mon Feb 12, 2018 8:03 pm

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. This may mean that you can't view them at all, or it may just mean that you need to log into the forum to view them.
User avatar
Martin Wynne
 
Posts: 2358
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 postby Dave Gehman » Mon Feb 12, 2018 8:28 pm

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?
Dave Gehman
 
Posts: 232
Joined: Sat Sep 23, 2017 9:05 pm

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

Unread postby Martin Wynne » Mon Feb 12, 2018 11:06 pm

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. This may mean that you can't view them at all, or it may just mean that you need to log into the forum to view them.
User avatar
Martin Wynne
 
Posts: 2358
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 postby Dave Gehman » Mon Feb 12, 2018 11:21 pm

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.
Dave Gehman
 
Posts: 232
Joined: Sat Sep 23, 2017 9:05 pm

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

Unread postby Martin Wynne » Mon Feb 12, 2018 11:55 pm

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.
User avatar
Martin Wynne
 
Posts: 2358
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK


Return to Help & Manual 7 Forum

Who is online

Users browsing this forum: No registered users and 2 guests