Using Snippets or Micro-Content for CSH?

[doloremipsum]

We have the most basic of basic help systems right now, and we would like to in future implement some CSH. I know that we can link individual buttons in the software to particular pages (topics) in the help.

Is it possible to do a similar thing with snippets (or micro-content)? I'm imagining a system where each of the (many hundreds of) fields/checkboxes has a help button which expands into a snippet callout about that particular feature. It's the kind of thing you see on lots of websites, but I'm not sure how to achieve it from my Flare content.

Initial thoughts: make a TOC which is just the relevant snippets, publish to clean HTML, use CSH techniques to link them to the callout buttons?

[devjoe]

Snippets themselves are not topics, and don't generate something in the output that you can link to. However, you can create a topic that just contains the snippet, assign an alias and number to it, and use that for CSH. You can also put bookmarks within a topic that contains a bunch of content to link to specific places within it (such as a table that describes many fields located on one screen), and link the CSH to the individual bookmarks to jump to that place within the topic.

I haven't explored using micro-content yet for anything other than search result hints, so I can't answer that part of your question.

[doloremipsum]

That is interesting! I had some assumptions about how snippets worked because if you put a snippet in a TOC for a print output, it just inserts itself in the correct place in the output as if it were a topic. I just tested the same for HTML5 and it's completely different: for some reason the build process wrapped the snippet content in the <pre> tag and just gave me the unprocessed code on the output page.

Seems like a weird choice - I would personally expect it to treat the snippet as if it were a topic, especially since it is a complete page (with declarations etc) in its base form.

Anyway, looks like there's some discussion about it here: viewtopic.php?f=9&t=31611&p=136755

Current status seems to be inconclusive: microcontent can probably be used for this, with developer input, and Madcap is hypothetically working on something more integrated. I'm cautiously optimistic that by the time I actually get time to work on this there will be something in place to work with.

[ChrisBradley]

There was just a thread on LinkedIn about this. The UI software development kits already contain tools for developers to implement field-level help in their applications, in the most efficient way possible. Any workaround in Flare will add a ton of unneeded overhead and work for both the writer and developer. Here is how it works:

When the application loads a screen, there is a back-end properties file that loads behind the scenes. This plain text property file contains a long list of key-value pairs of button labels and button definitions. Something like this:

save=Saves the document.
open=Opens the document.
close=Closes the document.
moreInfo=<a href="www.helpme.com'>Click Here For more Help</a>
etc...

While the developer adds new buttons to the screen, they are also adding the labels and help definitions to the properties file. The developer adds the properties file name and location to the metadata of the UI, so the software knows how to access it. The SDK will have the tools built in to display the text as pop-over help when the field is selected (or however the devs decide to access it). In JAVA, the developer can even add variables to the text so they can programmatically change based on events.

If you want to begin including field-level help in your applications and not be a nightmare to your developer, then you can offer to edit these properties files as part of the development process. They are easy to identify (in Java they end in .properties) and are plain text. They're part of the code, so they are easy to manage as part of the Agile process.