Sanity check - am I revising TOC number entries right?

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

Moderators: Alexander Halser, Tim Green

Sanity check - am I revising TOC number entries right?

Unread postby Dave Gehman » Thu Jan 24, 2019 5:19 pm

(I know that counter variables aren't part of the TOC world and am able, almost, to understand why, per https://www.helpandmanual.com/help/index.html?hm_working_variables_countersuser.htm. However, I have a recurring need to re-number TOC entries that are numbered.)

In the self-guided training portion of our online WebHelp, we have 18 topics. The heirarchy is Table of contents > Self-guided training > [18 topics, with child topics under them]. These are training units. We need to number them explicitly: Unit 1 [subject], Unit 2 [subject] and so on.

Under each are exercises and summaries - topics headed "Unit 1 Exercise," "Unit 1 Summary" and so on down the 18.

We are still in the process of figuring out the sequence of learning that has to go into our complex software. The Unit Number changes often.

For example, Unit 3: Rules has to become Unit 4 - and Unit 16: Methods has to become Unit 3, because we've learned that comprehending Methods makes comprehending Rules much easier.

It's easy enough to edit the TOC Title and to re-arrange units along the TOC in the Project Explorer. What's not changing with the Title edit is the TOC Topic ID. I've learned that I need to change the Topic ID - otherwise, making links to them is mind-boggling (I can't manage to keep my sanity if, when I want to link to the newly-renumbered Unit 3: Methods, I have to remember to link to it as "Unit-16-Methods".)

So - my method is:
1. Edit the Title. Easy enough - F2, change the number
2. Edit the Topic ID - not so easy. There is already a Unit-3-Exercise and a Unit-3-Summary. H+M complains about that.
...so...
3. I change the Topic IDs to "Unit3-Exercise," "Unit3-Summary" (losing the hyphen between "Exercise" and the number).

Is there a better way?
Dave Gehman
 
Posts: 389
Joined: Sat Sep 23, 2017 9:05 pm

Re: Sanity check - am I revising TOC number entries right?

Unread postby Martin Wynne » Fri Jan 25, 2019 2:30 am

Hi Dave,

Unit-16-Methods

You don't need the number on the topic ID. Just make it methods_unit.

And if you value your sanity when creating links without errors, make the topic ID all lower case and use underscores for spaces. I've been banging on about this on this board for years, and there was one glorious version of H&M6 which actually did it automatically. If you use hyphens for spaces, you are then unable to use proper hyphenated words in the title.

cheers,

Martin.
User avatar
Martin Wynne
 
Posts: 2519
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Sanity check - am I revising TOC number entries right?

Unread postby Dave Gehman » Fri Jan 25, 2019 3:30 am

Martin Wynne wrote:You don't need the number on the topic ID. Just make it methods_unit.


Unfortunately, I do have to put the number in here. My liaison with training is OCD and he's saying, if it's numbered in the training, it has to be numbered in the help file... otherwise it's not consistent. Yes, a foolish consistency is the hobgoblin... and so on... but consistent it must be.

And if you value your sanity when creating links without errors, make the topic ID all lower case and use underscores for spaces. I've been banging on about this on this board for years, and there was one glorious version of H&M6 which actually did it automatically. If you use hyphens for spaces, you are then unable to use proper hyphenated words in the title.


I'll likely take your lead on this one.
Dave Gehman
 
Posts: 389
Joined: Sat Sep 23, 2017 9:05 pm

Re: Sanity check - am I revising TOC number entries right?

Unread postby Tim Green » Fri Jan 25, 2019 7:23 am

Hi Dave,

Basically, you should try as hard as you possibly can to NEVER EVER change a topic ID after it is created. All links to the ID within a project are automatically updated when you edit it, that is not the problem. However, the ID is also the name of the topic file and, through that, the name of the HTML file in your WebHelp or CHM output. If you use WebHelp or CHM and anything anywhere is linking to a topic from outside -- for example a user who has bookmarked a page, another website linking to your page or even links in your software to your help or links from other help files -- all those links will no longer work when you change the topic ID.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Tim Green
Site Admin
 
Posts: 20887
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany

Re: Sanity check - am I revising TOC number entries right?

Unread postby Martin Wynne » Fri Jan 25, 2019 8:55 am

Dave Gehman wrote:Unfortunately, I do have to put the number in here. My liaison with training is OCD and he's saying, if it's numbered in the training, it has to be numbered in the help file

Hi Dave,

By all means have numbers in the topic title, and move them around and edit them if you want to. But there is no need to repeat the numbers in the topic ID and file name, because no user ever sees that in normal use.

As Tim says, edit the topic ID at the time of creating the topic, and then try not to change it later. Otherwise you will get in a terrible muddle.

In my experience the auto-creation of the topic ID by H&M is a mixed blessing. I always edit it immediately when creating a new topic. You can edit the topic title at any later time (F2) and you may do that several times in fine-tuning your Help, after which there will be no exact correlation between the title and the ID, so you may as well not start off with any. The needs of a title and a file name are two different things -- one is for the user and the other is for you.

Usually I don't know the exact title of a topic until I have finished writing it. I often start off with a dummy placeholder title just to get started.

cheers,

Martin.
User avatar
Martin Wynne
 
Posts: 2519
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Sanity check - am I revising TOC number entries right?

Unread postby Dave Gehman » Fri Jan 25, 2019 1:13 pm

Tim Green wrote:Basically, you should try as hard as you possibly can to NEVER EVER change a topic ID after it is created.


So, let's start with the bad news:
Both the software I'm documenting and well as the methods for training people on it are essentially at beta (or earlier) stages. The user interface of the program is about to be massively changed along with terms used for quite a few operations that have proven to be easily misunderstood.

Changing topic names and ordering is a good tenth of my work.

The good news:
Right now, there are only 12 users outside our company. I'm not worried about any bookmarks just yet.

When I go to create a link, the drop-down list of topics for the target consists of the Topic IDs. I use that extensively to set up new links.

I'd go nuts trying to link to 'Unit 5-Children' if it's in the list under an unchanged Topic ID as "Unit-12-Children" because it got moved in its lifetime... or, worse, trying to link to 'Base Library' if its original Topic ID is "Primary-Resources."

I'd have to keep an external mapping document, print it out, pin it to my office wall, and refer to it with almost every new link.
Dave Gehman
 
Posts: 389
Joined: Sat Sep 23, 2017 9:05 pm

Re: Sanity check - am I revising TOC number entries right?

Unread postby Martin Wynne » Fri Jan 25, 2019 1:23 pm

Dave Gehman wrote:
Tim Green wrote:I'd go nuts trying to link to 'Unit 5-Children' if it's in the list under an unchanged Topic ID as "Unit-12-Children"

Hi Dave,

But you won't go nuts if its ID is simply "children". The ID doesn't need the title number. You edit the ID in the Topic Options tab.

cheers,

Martin.
User avatar
Martin Wynne
 
Posts: 2519
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Sanity check - am I revising TOC number entries right?

Unread postby Dave Gehman » Fri Jan 25, 2019 1:27 pm

Martin Wynne wrote:But you won't go nuts if its ID is simply "children".


And I wouldn't go nuts if the drop-down list in the Links dialog were drawn from the Title rather than the Topic ID...
Dave Gehman
 
Posts: 389
Joined: Sat Sep 23, 2017 9:05 pm

Re: Sanity check - am I revising TOC number entries right?

Unread postby Martin Wynne » Fri Jan 25, 2019 1:35 pm

Dave Gehman wrote:And I wouldn't go nuts if the drop-down list in the Links dialog were drawn from the Title rather than the Topic ID...

Hi Dave,

I wouldn't be in favour of that. I get familiar with the ID list I've created and I wouldn't want it to change when I edit the topic titles.

cheers,

Martin.
User avatar
Martin Wynne
 
Posts: 2519
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Sanity check - am I revising TOC number entries right?

Unread postby Martin Wynne » Fri Jan 25, 2019 2:07 pm

Hi Dave,

Another reason you might like to create the topic IDs independently of the titles, is that you can include the topic parent-child nesting in the ID. For example, if you have chapters and topics:

Code: Select all
Fruit Juice
  Apple
  ---
  Orange
     ---
     Bottling Processes in UK
     ---

(The header on the topic page would be say "Bottling Processes for Orange Juice in the UK" which is too long for the TOC.)

Then the topic ID can be fruit_juice_orange_bottling_uk, and you can find it every time, listed with its fellow child topics.

cheers,

Martin.
User avatar
Martin Wynne
 
Posts: 2519
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Re: Sanity check - am I revising TOC number entries right?

Unread postby Tim Green » Fri Jan 25, 2019 2:46 pm

Hi Dave,

Rather than arguing in circles about this I think we need to make it clear that "Don't edit topic IDs" is not a recommendation. It is an absolute requirement that you have to live with if you are using WebHelp or CHM. It isn't something you can argue about or have differently. It is something that you have to accept, whether you like it or not. Regard it like death and taxes.

If you edit your topic IDs after publishing something in WebHelp or CHM the problems you will create for yourself will make all your other troubles look like a tasty apple pie.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Tim Green
Site Admin
 
Posts: 20887
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany

Re: Sanity check - am I revising TOC number entries right?

Unread postby Dave Gehman » Fri Jan 25, 2019 3:21 pm

Tim Green wrote:Rather than arguing in circles about this I think we need to make it clear that "Don't edit topic IDs" is not a recommendation. It is an absolute requirement...


Sad to say, it's already done. I've republished to WebHelp several times (under new Version numbers & dates) -- every publish involves deleting all existing WebHelp files on the server, then uploading the new ones. What am I about to experience? So far as I can tell, nothing dire has happened.

Meanwhile, I need to have options in the "Target" drop-down list in the Link Dialog match the title of topics, and not the Topic ID if that's different from the Title.

My new workflow will be:
In the working Project in H+M: Open the topic whose title is about to change.
Select all > copy contents to a parallel, second H+M project --- EDIT: or to my XML editor
Delete the topic in the working Project.
Create a new topic with the new desired name.
Paste the content from the parallel project --- EDIT: or my XML editor

There's a chance I can write an external macro to do this.
Dave Gehman
 
Posts: 389
Joined: Sat Sep 23, 2017 9:05 pm

Re: Sanity check - am I revising TOC number entries right?

Unread postby Tim Green » Fri Jan 25, 2019 3:42 pm

What am I about to experience? So far as I can tell, nothing dire has happened.

If anyone has linked to the topics that you have changed those links will be dead. If anyone has referenced those topics anywhere those references will no longer be valid. If you have any links to topics in your project from other projects those links will no longer work.

Quite apart from all this it's generally just unnecessary -- unless all the links to your documentation everywhere in all versions are automatically changing at the same time as your WebHelp is changing.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Tim Green
Site Admin
 
Posts: 20887
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany

Re: Sanity check - am I revising TOC number entries right?

Unread postby Dave Gehman » Fri Jan 25, 2019 3:51 pm

Tim Green wrote:If anyone has linked to the topics that you have changed those links will be dead. If anyone has referenced those topics anywhere those references will no longer be valid. If you have any links to topics in your project from other projects those links will no longer work. [Generally unnecessary unless] the links to your documentation everywhere in all versions are automatically changing at the same time as your WebHelp is changing.


A bit of a relief, because:
-- The entire universe of external users who might have created a bookmark is 12 people. Any of the 40 internal users can (and will) crab at me and I can set them straight.
-- No other projects reference this one.
-- All other outputs (Word and PDF so far) are done on demand for a specific need -- review, mainly.
Dave Gehman
 
Posts: 389
Joined: Sat Sep 23, 2017 9:05 pm

Re: Sanity check - am I revising TOC number entries right?

Unread postby Martin Wynne » Fri Jan 25, 2019 4:09 pm

Hi Dave,

It's not the end of the world, because if you think anyone might have created a dead link you can easily put a redirect on the server. Ask your IT person to do it for you if necessary. It's extra work, but only takes a minute or so to do.

cheers,

Martin.
User avatar
Martin Wynne
 
Posts: 2519
Joined: Mon May 12, 2003 3:21 pm
Location: West of the Severn, UK

Next

Return to Help & Manual 7 Forum

Who is online

Users browsing this forum: No registered users and 3 guests