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.
Note... We do have some customers with zero access to the internet. Serving from a centralized location would require us to ship a mirror embedded in the product... We still have the problem, we just kicked the can down the road. And we added to complexity.
Robert says:============In the real world, there's still a lot of installed software with
embedded online help. Once that ships and a customer installs it, the
help doesn't get updated until they choose to install a later release.============
Absolutely. And one important factor is binding to the version of the GUI. There are two aspects for this.Â
One is that you want the user to be as close to the GUI as possible when reading the content. We implement this via progressive disclosure... From GUI elements, through tooltips, and on down to the help topics, and further - say white papers, community content, etc. But the point is user experience, and getting as much content as possible into the GUI seems the right way to go. Yet we want reuse, which means putting the same content into topics if and when appropriate (or conversely, extracting content from topics to put into the GUI). For security and performance reasons, it's hard to imagine that you can get this content from a centralized server, unless the product is SaaS from a centralized server.
Another has to do with the validity of the information. If the product has changed, which version of the content will you get. We have customers who, for various reasons, update along different time frames. We release a new version every quarter. That's a lot of existing versions out there... Welcome to Agile. We all suffer the same issue when we turn to Google for help in common products. I wish I had a nickle for each time I got halfway through a Google hit just to realize that the version is wrong, and all the steps to do X simply aren't there anymore. Make the differences more subtle, and you have a serious problem... One configuration switch has changed but otherwise the versions look the same.Â
We have found that there are categories of information that make sense in a centralized server, and categories that are bound to the version of the product. For those reasons alone it makes sense to question the wisdom of a centralized server for all content.
Daniel says:===================At my current position, we have made the embedded help file update-able
through the software's update feature. This means a customer doesn't have
to install an entire release, but just an update package. Whether or not
the customer has to re-validate their entire install after downloading an
update package, is something that the customer would have to decide based
on their SOPs (pharmaceutical industry).===================
We're looking at a microservices architecture -- the docs can be a separate component. I wonder if such a compliance-sensitive enterprise could set different validation requirements to different components. If the docs are served in a separate component, and that's all that you update, then would the customer need to validate?Â
We currently ship our product as a set of servlet components... GUI, logic, and other. There's nothing to keep us from separating the docs from the GUI component and providing them in their one component. That would isolate doc updates.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
