Guidelines for replacing a help system

[TR Lisa]

Looking for guidelines, best practices, or success stories from anyone who has replaced a legacy help system with a new one. The HTML help project I inherited is not fixable. I need to start over. All topics will have new URLs. Need an approach that minimizes customer impact cause by all the links that will break Anyone gone through this that can offer any advice at all?

[Jbleasdale]

I went through this recently.

We did a total company website redesign at the same time as well. The marketing team set up a lot of static re-directs to keep as many of the links alive as possible.

But forwarding the links from the old system to the new Flare site was not doable as the old system didn't allow any control of the link routing. We re-directed the main URL's (which belonged to us) to the new home page.

In terms of best practices...

• Give yourself plenty of time, building a Flare project is a complex process (especially if you are doing it for the first time).

• Ask for help when needed. Flare consultants, or web developers are often much quicker at the advanced CSS stuff and they're worth their weight in gold.

• Use source control! My first couple of Flare projects didn't, but now I use it and I could not imagine doing a project without it. Think about the source control structure too and whether you want to use Flares internal tools, or external tools.

• Create a structure for the project, so its easy to know what is where. My resources folder mimics the structure I use for my topics, so finding images has a similar path to finding the topic.

• Naming topics like "Product-Setup-Steps.htm" helps to make the URLs look tidy. Putting spaces results in "Product%20Setup%20Steps.htm" in the URL which doesn't look nice.

• Use the starting over process to overhaul all the legacy stuff you want to get rid of. Make page structures and guidelines and if content doesn't fit into these new guidelines, redevelop it (or get rid entirely).

Starting over its a lot of work, but can be really positive if done right.

Best of luck!

[NorthEast]

Can you be more specific what you're doing?
You're moving from HTML Help (CHM) to what - HTML5 help?

If you're moving from HTML Help (CHM), then presumably the links are just from your application to the help CHM file. There are no external links, like you have for web-based help.

So changing those links is going to be a job for your developers - instead of having CSH links to a CHM, they're replacing that with CSH links to a different output (I'm guessing HTML5).

In the simplest scenario, your developers just change how they make the CSH calls, but use exactly the same IDs in those calls.
Provided you set up the header and alias file in Flare with those IDs, and map them to appropriate topics, then the links from the application will work.

Presumably you had a header file in your old HTML Help, and the application used an ID number in CSH calls.
You can do the same in HTML5 help - and even use the same ID numbers if you wanted to. HTML5 help can handle CSH calls using identifiers (text strings) or ID numbers.

So you could take the header file from your old help project, and use that in Flare to set up the alias file in your new Flare project.
Or you might try importing the old CHM into Flare, which I *think* also brings in the header file information
http://help.madcapsoftware.com/flare201 ... -Files.htm

[TR Lisa]

Thank you for the replies. I'm pretty familiar with Flare so am comfortable setting up the project and topic structure. Although I will review the Flare guidelines to make sure I'm up to date on best practices and the newest features.

Am replacing HTML5 output with HTML5 output. We don't have CSH developer calls to worry about. A few of our application pages have "page help" that's hard wired by the devs, but it's just a straight URL call so not worried about those. Users won't know those URLs changed.

Reason I'm replacing it is because it's 2 million words written by countless prolific, style-averse authors over numerous years and contains an unimaginable amount of outdated content. Topics have this weird, mysterious, numbered naming conventions and are organized in crazy nested folder structure that breaks the publish due to too-long file names. Topic are very long, vague, poorly written, and poorly organized, with the old "Return to Top" links. It's a snake pit of inconsistency, redundancy, and staleness. The Flare project structure is unwieldy, filled with legacy elements, and almost unrecognizable. But you can't touch anything without fear of breaking the publish in some unrecoverable fashion.

We send a ton of content to customers that includes many links to Help topics. A lot of customers have developed their own training materials, also with many links to Help topics. So a lot of customer links are going to break. I was hoping there might be some temporary redirect approach that would let them get to new content via old links, for a period of time during which we'd communicate the upcoming end of life for those links. Also considering rolling out a smaller "light" version of the new Help and including a link to the old Help system as a temporary transition management measure. Can't decide if that's a good idea or not. It would leave old links in place at least, and allow time to communicate the change.

It's going to be fun I can use all of the great wisdom y'all have to share!

[devjoe]

Web servers have a web of creating redirects, so you can specify that when they try to go to example.com/foo they get example.com/bar instead.
This is outside of the project itself, though, and the way you set this up will depend on the specific web server. You should discuss this with the webmaster who maintains this web server.
And you will need to make a list of all the current URLs that you want to redirect and where you want to send them.

[TR Lisa]

Thanks. Sounds like a joyous undertaking. Can't wait!

[RamonS]

Does the help need to be ADA compliant? In that case redirects are still possible, but you want to put a page up with a delay so that screen readers or other assistive technologies have time to relay the information. It is generally good practice anyway to tell users that although they asked for "ABC" why they will get "123" instead.

[TR Lisa]

No ADA required. But realizing we have more than 2000 topics, I don't think individual redirects are feasible. It's looking like the plan to roll out a Help Center "lite" with the core content rebuilt, that links to the legacy help structure for a period of time during which we knock em over the head at every touch point about the permanent removal, is the way to go. I need to think it through and map it out and see what gotchyas I'm going to have to deal with, or that are showstoppers. Trying to get this done late Q1 in line with a UX refresh.