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.
Re: Online help for GUI/web-based config app of HW telecom
Subject:Re: Online help for GUI/web-based config app of HW telecom From:Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com> To:Erika Yanovich <ERIKA_y -at- rad -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Mon, 2 May 2016 08:08:50 +0000 (UTC)
Hi Erika...
I wonder if this isn't an excellent use case for a phone app that provides the docs. The field personnel can load the app n the phone before coming onto the site, and have it available.Â
cud
From: Erika Yanovich <ERIKA_y -at- rad -dot- com>
To: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>; "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Sent: Sunday, May 1, 2016 2:23 AM
Subject: RE: Online help for GUI/web-based config app of HW telecom
Hi Chris,
To start from the end, for a change, CLI is not fading away at all. All carrier-grade telecom equipment "talks" CLI, in fact we made the move from menu-driven to CLI a few years ago. This industry loves scripts, i.e. CLI batch files. That being said, some vendors also offer element management apps to configure the products via GUI.
I am not annoyed at all by your question, in fact I do exactly what management is used to, PDF manuals for the CLI. However, for the GUI-based apps, I want to do Help *in addition*.
This is where the location of the Help files starts being an issue. The best option would be to include them in the product, but in small products memory is limited and they don't want anything to touch their precious code. The second option is download the Help system to the laptop used for the config and point the Help button to a predefined location and file name. They dislike this option as well, as they don't want to need anything else on that laptop. The third option is what you suggested: pointing the Help button to a server. This requires internet access, which is not always the case for remotely located equipment.
So now you have the full pic.
Erika
-----Original Message-----
I know somebody who worked for Harmonic Inc, which makes AV stream encoders. This is probably a level beyond what you're talking about. They delivered full-blown help systems with their products, but setting up multiple streams to be encoded to different protocols, and perhaps spliced together -- that's non-trivial. They might have lower-level (less complex) hardware that also includes online docs.
A question -- in spite of how annoying I personally find it when people ask,"Why do you want to do it THAT way?" -- Why do you want to do it that way? If your mgmt is married to delivering a separate PDF, then why not compromise? Write the docs, generate a PDF, generate hosted HTML5 output... Hey, why not generate a phone app? And have your help link bring down the hosted HTML doc. Then your field people can access the docs in any way they like... Print, Web, Phone.
I suggest this in spite of my personal religion, which mandates that all content should be distributed with the device. How do you know what version of the docs you need? If the docs are with the device, the version is correct by definition. But the combination of device and culture/infrastructure might make distributed docs inappropriate. Also, I'm a firm believer in embedding as much content as possible in the GUI itself. Make explanations that expand out with the GUI. Not useful for CLI, but isn't CLI fading?Â
cud
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com