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.
This email responds to both Matt Floyd's original email, and Glenn Maxey's
followup response.
Matt Floyd asked:
> I am preparing to document a new subset of our software application
> that uses dynamic GUI - a means that allows our users to build their
> own interface screens - placing certain defined objects on windows and
> dialog boxes - according to their specific needs and how they prefer
> to collect information.
[snip]
> In the future I would also like our customers to dynamically generate
> documentation based on the objects they have placed on their interface
> screens, using a online database publishing software with a FrameMaker
> to PDF layout component (such as Miramo).
>
> Has anyone else out there documented a dynamic GUI application? Is
> there a better way of describing a software application that can be
> totally set up by users?
While I know that your solution is probably do-able, I believe that my idea
*may* be easier to accomplish, and would probably require a *lot* less initial
outlay of cash. And we all know that it's usually easier to get an idea past
management if it isn't going to cost them a lot! I remember going to an STC
presentation on database-backed FrameMaker tools, and there was one called
Camelot or Guinevere or Merlin or something like that that was many thousands
of dollars...and that didn't include the support package.
Those who have read my posts can probably just about figure out what I'm going
to recommend right about now, since I seem to bring it up as a potential
solution for lots of different situations. I believe that you can make
JavaServer Pages (JSP) work for your particular situation.
Let me preface this with the requirements for this to meet your needs. First
would be that you can have your documentation on a web server for your users to
access over an Internet connection. If you don't have that, then it becomes
much more involved creating dynamic HTML-based documentation (though, from what
I read recently, it *is* now possible, as you can encapsulate a JSP-enabled web
server within an application). Second is that you have a rudimentary knowledge
of Java, or have access to someone who does. Believe me, my understanding of
Java is pretty limited, and I've been able to do some Really Cool Stuff in JSP.
Assuming you meet these requirements, let me tell you what you can do with it.
With JSP, you can interface with a database using JDBC drivers. Very simple,
once you find out how to do it. You figure out what two lines of code you need
to access the database, and you've got it covered from there on out. You can
query the database to your heart's content.
However, if you don't want to have a database on the back end, you can *still*
make this work for your users.
I am working on a (free) web site to teach technical writers how to use JSP to
enhance their web-based documentation. On this site, I am adding several
wizards that build JSP components for you (almost completely eliminating your
need to know how to code *any* Java, whatsoever). One of the components that
will be generated is called a tag library. A tag library basically encapsulates
some Java functionality into HTML-like tags. You then use these tags to invoke
the functionality.
The tag library component that the site will build for you is a
conditionalization tag, that will work much like FrameMaker's conditional text
feature. You encapsulate a portion of the page in the tag, and it will
determine, as the page is being sent to the customer, whether to include that
part of the page. The code might look something like this:
<Taglib:CustA><p>If, and only if, the person requesting this page works for
Customer A, then display this text.</p></Taglib:CustA>
The first time a user accesses the documentation, they indicate who they work
for, and then all of the documentation will be customized so that it only
displays the information appropriate for this customer. You can either require
that they log in every time they access the documentation and store their
settings in a database, or you can put a cookie on their machines to store that
information (or let them choose, even).
One great side-benefit of doing things this way is that it lets your
customers/clients modify the documentation *one time*, and have it remain
customized forever. The <Taglib:CustA> tag will remain in there for release
2.0, 2.1, 3.0, 3.5, and on. They won't have to customize the documentation
every time a release comes out.
For those interested in learning how to do this, keep an eye on the Techwr-l
daily email, as I will be listing the site in that as soon as it is ready.
My response to Glenn Maxey:
> From the perspective of most users, dynamic applications aren't. That
> is to say, they don't use them that way to nearly the extent that they
> could, if at all.
>
> Case in point: how many times have you seen someone using a browser
> who didn't even bother changing the default unvisited/visted link
> colors from the hard-to-read blue/purple or link underlining? How many
> times do they regularly turn toolbars on and off?
I think this is a case of knowing your users. If you're dealing with
shrink-wrapped software, then maybe most of your users *won't* customize the
application.
However, if you are dealing with a hospital, you can almost be guaranteed that
they will modify it in some way. Every hospital has its own way of collecting
information, controlling who has access to it, and so on. You'd be hard-pressed
to find any major application in a hospital that hasn't been modified in some
manner, either by the vendor or by the hospital IS/IT department.
__________________________________________________
Do You Yahoo!?
Make international calls for as low as $.04/minute with Yahoo! Messenger http://phonecard.yahoo.com/
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe. http://ieeepcs.org/2001/
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
