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.
A branch of us has been developing and selling a webbish GUI for provisioning and managing our products, for a couple of years. Since we acquired a very market-testing-oriented PLM for the GUI, it is getting a major, ground-up rework. Our newest writer is handling that. But the actual hardware/software products have had only command-line admin and C-language and various other APIs for a couple of decades. Itâs like pushing string to get the command-line syntax and âhelpâ text expanded to provide a little guidance and context. I bridge the gaps by documenting.
I use straight-up representative diagrams, âcuz I havenât figured out any useful metaphors. :-)
From: Lois Patterson [mailto:loisrpatterson -at- gmail -dot- com]
Sent: August-06-14 4:53 PM
To: Robert Lauriston; McLauchlan, Kevin
Cc: techwr-l
Subject: Re: Software documentation that uses effective visual metaphors?
Yes, it's more a matter of no UI than bad UI for what we are trying to explain.
On Wed, Aug 6, 2014 at 1:32 PM, Robert Lauriston <robert -at- lauriston -dot- com<mailto:robert -at- lauriston -dot- com>> wrote:
Not everything has a UI. I used metaphorical diagrams to explain a
complex versioning model in an object-oriented DBMS that had no UI,
only command-line admin and SQL clients, a C API, and bindings for
Java, C++, and various other languages.
On Wed, Aug 6, 2014 at 1:23 PM, McLauchlan, Kevin
<Kevin -dot- McLauchlan -at- safenet-inc -dot- com<mailto:Kevin -dot- McLauchlan -at- safenet-inc -dot- com>> wrote:
> [no-help-at-all 'response' follows]
>
> So, what you are saying is that the designers and developers of the software have stopped short of making an excellent UI, and you-and-your gang are now tasked with bridging the gap by documenting?
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
