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.Â


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.


-----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?Â


Visit TechWhirl for the latest on content technology, content strategy and content development |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

RE: Online help for GUI/web-based config app of HW telecom: From: Erika Yanovich

Previous by Author: Re: Help with a survey
Next by Author: Re: integrating authored content with generated API docs
Previous by Thread: RE: Online help for GUI/web-based config app of HW telecom
Next by Thread: RE: Online help for GUI/web-based config app of HW telecom products

What this post helpful? Share it with friends and colleagues:

Sponsored Ads