Supporting Customer Extension of Help

[mwright123]

Hello,

I've recently been asked by Senior Management to explore how to allow our customers to extend/customize the help system that we provide for them. A customer's actual implementation of our product can be very specific to that customer, which means our out-of-the-box help is very general and only *sometimes* suits the customer's needs. As a result, making it possible for the customer to extend/customize the help is desirable.

Might Flare be a good option for this somehow since it is open standard? And if so, how?

As additional information, currently we use RoboHelp to produce a context-sensitive, field-level help system. The information is really required at the field-level given the industry. So the user clicks F1, and up pops a page that describes how to configure that field. Nothing more that that. ...but that is the system Management would like customers to be able to extend/customize.

Any thoughts or insight would be greatly appreciated!

Thanks,
Mary

[BedfordWriter]

Ellis Pratt (frequent MadWorld speaker) mused on that topic in his blog, a while back:
https://www.cherryleaf.com/blog/2016/01 ... y-clients/

I've recently started to use a variation on option #3, empty placeholders. It's been used in one project so far, to everyone's satisfaction. (I use TopNav help)
But, so far as I can figure, there is no way to make the new extension topics searchable or add them to the menu.

Things to consider for your project include making sure that you don't blow away the customer's topics when they upgrade to a new version of your program.

[mwright123]

Thank you very much for this helpful reference! And for the extra considerations. There seems to be really no easy solution to meet this type of need.

I will review the article you referenced thoughtfully.

Cheers,
Mary

[arkana]

Ellis Pratt (frequent MadWorld speaker) mused on that topic in his blog, a while back:
https://www.cherryleaf.com/blog/2016/01 ... y-clients/

I've recently started to use a variation on option #3, empty placeholders. It's been used in one project so far, to everyone's satisfaction. (I use TopNav help)
But, so far as I can figure, there is no way to make the new extension topics searchable or add them to the menu.

Things to consider for your project include making sure that you don't blow away the customer's topics when they upgrade to a new version of your program.

Hi, Could you share how you implement option 3? We got a similar request from managers and are curious to learn how other ppl do this.

Thanks

[BedfordWriter]

What I do is pretty basic. Won't get me invited to speak at MadWorld anytime soon.

My solution allows a user to create topics that they can open with an F1 press from within our program. That works because our program is used for application development and it's easy to add a line of code to a custom page to pick up the F1 press.
It depends on the alias file being given a bunch of numbers for files that don't exist in the shipped documentation. The customers can provide those files.

One big drawback is that it won't age well. Their custom pages will look pretty much the same years from now when I've completely redesigned the rest of my help system. In fact, bits may break and they will probably need to copy their content to an updated template.

[arkana]

What I do is pretty basic. Won't get me invited to speak at MadWorld anytime soon.

My solution allows a user to create topics that they can open with an F1 press from within our program. That works because our program is used for application development and it's easy to add a line of code to a custom page to pick up the F1 press.
It depends on the alias file being given a bunch of numbers for files that don't exist in the shipped documentation. The customers can provide those files.

One big drawback is that it won't age well. Their custom pages will look pretty much the same years from now when I've completely redesigned the rest of my help system. In fact, bits may break and they will probably need to copy their content to an updated template.

Thanks for the response. So the workflow is that the customer copies some HTML files to a specified folder and modifies the alias file upfront from the help server, and the custom help page will work? Do you provide a script or utility for customers or this is a manual process? And did you provide a template to the customer? Something like a skeleton HTML file with supported tags for customers to fill in the blank, for example.

Yeah, the content and their formats are out of control if they are not created/maintain by you. Not sure if the CSS shipped with Flare-generated docs can control the styling of custom HTML pages. If this can be achieved, the look and feel of the custom doc can be updated and controlled in some way..

[BedfordWriter]

Correct about copying a template HTML file (which I provide and keep up-to-date in terms of format) to a specified folder. Not about the alias. I've done that ahead, setting aside 100 ID values. Those match a set of designated file names in the target folder.
You'll have to have those files when you build, but be very careful not to ship them. Don't want to over-write the customer's version. I put start and end marks in the template so that they know where to edit.

It makes sense that this is hard to do. The grail is to have a way to extend a Flare project, adding in all the nifty MadCap features, by someone who doesn't have Flare. That ain't gonna fly!

[arkana]

Correct about copying a template HTML file (which I provide and keep up-to-date in terms of format) to a specified folder. Not about the alias. I've done that ahead, setting aside 100 ID values. Those match a set of designated file names in the target folder.
You'll have to have those files when you build, but be very careful not to ship them. Don't want to over-write the customer's version. I put start and end marks in the template so that they know where to edit.

It makes sense that this is hard to do. The grail is to have a way to extend a Flare project, adding in all the nifty MadCap features, by someone who doesn't have Flare. That ain't gonna fly!

Good tips. Thanks!