Embedded User Assistance

[mamarachel]

I've been using Flare for a while now to single-source help systems and printed documentation. Now, I've been asked to create embedded user assistance. This will consist of pop-ups or balloons that appear when a user hovers over or clicks on an icon in a web application. There will be no contents, no index, no search, and very little hyperlinking among chunks of user assistance.

Can/should I use Flare as the authoring tool? If so, could you please give me some hints on what others have done and how to get started? Thank you.

[RamonS]

That depends on which controls the developers want to use to implement that embedded assistance. Typically, the content is read as text string from the resource file, which should be an external file. Ideally, it is a flat file using tabs as delimiter and integers as keys (makes spell checking so much easier). If desired, that file can be obfuscated so that the end-user cannot tweak it and switch "Save" with "Delete". I once worked on a project where the application was able to read both plain flat files and the obfuscated files. We used the plain files internally and before release used a cheesy tool to apply the similarly cheesy obfuscation to it. That worked OK.
Some applications like Flare use XML files, which is OK, but requires special tools that allow for find and replace, spell check, and ideally a terminology list (sort of like a translation memory without the translations). I yet have to find a tool that works with XML files in the same comfortable way as many text editors do. Most XML editors cannot do spell check on the element contents only, but they choke on every tag.

Besides that, some development platforms have their own formats of flat files that are used to quickly provide for embedded assistance. In any case, I don't think Flare is the best tool for that since you really only need / have room for one or two sentences per case and Flare doesn't really produce the file format that you most likely will need.

[LTinker68]

If you're also including WebHelp output with that application, then you can create a second skin that doesn't have a navigation pane or toolbar and that has a set size. The programmer then uses a CSH call that includes that skin name as part of the CSH call so that the topic loads in that new skin. However, you're probably going to want to create a new set of topics since you're only going to have room for a few words. You can then set those topics up in Flare so that they can't be searched in the full WebHelp help interface in the browser.

If you're not including a WebHelp output with the application, you can still do the above, it's just that the output folder will have a lot more files and graphics that you don't need, so if you can, combine it with the main WebHelp output.

[doc_guy]

Lisa's answer is good, but only works if the UI is going to call a webpage. In most cases I've seen, the UI doesn't actually call a whole web page. It is more like RamonS said, it is a string called from a resource file.

Flare doesn't single source the resource file, so if the developers use this method, then you can't single source from Flare.

If however, the developers use a method that allows you to call a whole web page, then Lisa's answer will work for you.

[mamarachel]

Thank you!
Andi

[ktbCA57]

How does this differ from something like "field-level" help... where you hover over a field... or have "fly-outs", etc...

Thanks for any clarification you can provide.

kb

[RamonS]

There are two types of this kind of embedded help. One is the pop-up help you describe and the other is a more permanent help that appears as text label on the form. In the end they get pulled from the same resource file, only the display is different.
There is also field level help that opens the 'real' help file showing the specific help content in context. I personally like that better as it allows for maintaining one source, but it is a pain in the you know where to set up since you need a bookmark for each field description and have to assign it a map id. The only disadvantage here is that opening the help window can be time consuming and having an extra window float around may be annoying.

[mamarachel]

I've been learning more about this than I ever expected to need to know! For the new project, the developers won't be using resource files. Instead, all page assets (buttons, fields, persistent field label text, pop-up user assistance, links to HTML files, etc.) are going to be in a database. If the "pop-up" field in the database for a page has content, the page will display a control (maybe a question mark) for the user. For field-level user assistance, the developers' toolkit (RadControls by Telerik for asp.net) allows us to associate text with the field that is displayed by on-hover action. This would be a tooltip. The appearance of the whole thing (page and user assistance) will be controlled by CSS.

Now I am looking into how the user assistance writer (a.k.a., tech writer) can author for this environment. Of course, the toolkit has an editor, and the developers can give me access to the database, but there are some 3rd party tools (ComponentOne Doc-to-Help 2008 and DocumentX) that may be helpful.

By the way, when looking at the RadControls toolkit, it appears that there is a way to split a page into what appear to be frames (not actual html frames). I think it would be possible to then display an ordinary HTML help system in one of the "frames".

[RamonS]

I've been learning more about this than I ever expected to need to know! For the new project, the developers won't be using resource files. Instead, all page assets (buttons, fields, persistent field label text, pop-up user assistance, links to HTML files, etc.) are going to be in a database.

Is there any other reason besides "because we can" for stuffing bulkloads of static text into a database table? Risking to sound harsh, but this is the dumbest place things like that can go. How are changes supposed to maintained? What about translations? Will translators and tech writers be allowed to fork around in the database at free will? Are tools available to generate database update files? Which measures are taken to prevent that any lazy developer starts using text strings are references or indices? And how does one spell check field contents in a database table?
In order to keep installations current in regards to texts each database out there has to be updated. What about database backups? And what about the excessive overhead created by running the queries against the table to read out strings that are much faster retrieved from a flat file?

I came across this idea many times during over a decade now working in software development and never ever did I hear any convincing reason for bloating the database with stuff like that. The database is supposed to hold and provide those pieces of data that are subject to change through use of the application.
What's next? Any graphics and artwork are stored as BLOBs in some table? That's just crazy.

[tputkey]

Thanks RamonS. Your post made me laugh and it was sooo true. I just ran into this comment last week...