TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
It's even more basic than that. The help is part of the application, not even on an intranet.
When you say "Part of the application", what exactly do you mean? Is the application a server that delivers a GUI as a client, and it also serves up the help? If so, then read on...
This is what we do. Our product is a VM that serves up the GUI as an HTML single-page-application (SPA). We often (but not always) get installed behing a fully sequestered firewall -- hence no access to the outside world. For that (and many other reasons), we deliver the help as content that is delivered by the same server. To keep server footprint to a minimum (no processing of content, no implementation of search on the server, etc.), the help is also an SPA -- I've gone on ad nauseam about how we generate HTML out of DITA on the fly, etc. No need to repeat that here.
The product has a few options to "phone home" -- Users can enable a regular push to our domain that sends us diagnostics. Obviously that doesn't work in a sequestered environment. Users can also generate diagnostics locally, bundle them up, and email them to us. We sometimes require that for support. Apparently that is workable even for the sequestered environments.
We have a pubs email address for input from the field... Customers are free to send us a message at any time. Apparently that is also possible from a sequestered environment. It would not be a leap to include the JS that posts a form, captures information, and emails it. That form could be populated with things like the ID of the topic, or any other context you might find necessary. If all this happens in the help client, there should be no firewall problem. Or you can be even more secure and do the final emailing from the server. The only issue might be configuring the proxy to get the email out from the product domain, past the firewall. But I believe that would be part of the system config, not an issue you could control in your headers/footers. And I would guess that to be really friendly, you should include an option to disable this feature.Â
The only reason we don't do this ourselves is lack of resources. We can't afford to do anything that isn't immediately and directly critical to product success. Automating input about docs isn't on the list.
Another thing we could do is collect doc statistics in the diagnostic data. Then, when users send us their diags, pubs can have our own package of data to look at. This would be nice to have, but it's even further down on the list (because it would involve even more development).Â
IMO, delivering help from the product is awesome. It opens up so many possibilities... Like, you can integrate your doc content in the GUI, since both are just HTML delivered by the same server. We do this to implement walk-throughs that move through the GUI and open different GUI pages. Or you can call the API for THAT instance (since everything is behind the same firewall) and get real-time data about the system state. This is so much more fun than relying on a one-size-fits-all massive server/CMS complex out on the inter-webs somewhere.Â
So... Hope this is in the ball park for you.Â
cud
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | https://techwhirl.com
