Entries tagged as tools
I’m learning about Author-it’s HTML templates today, and how to insert Google Analytics code (or any other code, really, such as adding an automatically updating variable for “Last modified by” with user or date information.)
But my task today was to insert Google Analytics code. (As a prerequisite note, we already have all our documentation available on an external site at docs.imis.com.)
First, I created a Gmail account for our department. Next, I created a Google account. Then, I went to the Google Analytics page and signed up for an account there, entering the name of our externally-accessible documentation site.
At the end of the sign up process, Google gives you javascript code that you want to place directly above the closing body tag </body>. Fortunately, the way that Author-it sets up the HTML templates, all of your Author-it topic data is inserted at a point where the <aitdata> tag appears in your HTML template.
The HTML templates are typically stored in C:\Program Files\AuthorIT V4\Data\Templates\Plain HTML, although other types of HTML templates such as DHTML and HTML Help templates are also available. These are the files I discovered that Google Analytics needed to be installed on.
- I edited the body_template.htm file and located the <aitdata> tag. I copied the code from the Google Analytics page and pasted it below the <aitdata> tag.
- I edited the html_frameset.htm file and added the Google Analytics code in the <head> area as instructed by the Google Analytics help, which, as a side note, has a set of completely question-based articles, as in, all headings are written as a question. Fascinating. The topic is “What should I know about using Analytics with Framed sites?“
Now, republish the HTML from your Author-it topics and your Google Analytics code is available on each page. After about 24 hours we started collecting data.
Let me know your experiences using Google Analytics to monitor your user assistance site traffic - what metrics are you seeking? Are there any conversion goals we should set up? One metric I am considering is trying to monitor how often the Word .doc files are downloaded. Does anyone have tips or tricks for us?
Update: I found this blog entry, Tracking document downloads in Google Analytics, and it contains hints at what I need to do to track our Word document downloads. However, I think that this article from the Google Analytics Help, How do I track files (PDF, AVI, or WMV) that are downloaded from my site? contains the method I’ll try first.
Categories: tools · work
Tagged: analytics, author-it, AuthorIT, Google Analytics, HTML, HTML Help, site statistics, technical communications, techpubs, tools, user assistance, web site analysis, web traffic, XHTML
In trying to modify multiple Author-it topics (okay, 5,119 topics) with variable assignments, I have had to work with the XML output that Author-it exports.
To export to XML, you select a topic or multi-select topics, then right-click on the selection and choose XML > Save to file.
Turns out, Author-it outputs its XML encoded with UTF-16, but apparently most Windows applications understand UTF-8. When I tried to open my freshly export XML file, XML Copy Editor gave me an error.
So I had to discover how to convert the XML from UTF-16 encoding to UTF-8 (and you can’t just open it in Notepad on Windows and change the 16 to 8, there are other embedded characters indicating the encoding, and, well, it’s encoded.)
First, I used the identity transform documented many places, my favorite place being the XSLT Cookbook, to convert the Author-it output to UTF-8. Here’s the XSLT code for that:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:output encoding="utf-8"/> <xsl:template match="@*|node()">
<xsl:copy> <xsl:apply-templates select="@*|node()"/>
</xsl:copy> </xsl:template>
</xsl:stylesheet>
I just ran the above transform against the AuthorIT Objects.xml file I exported, using the Instant Saxon XSLT processor.
Then, I wanted to remove all <VariableAssigments> elements, effectively removing an entire node. Again, the identity transform (or copy transform) was effective. And, I learned that I had to identify the AuthorIT namespace thanks to this excellent helper article, Handling Default Namespaces on topxml.com.
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
xmlns:ait ="http://www.authorit.com/xml/authorit">
<!--Match everything using identity copy-->
<xsl:template match="@*|node()">
<xsl:copy>
<xsl:apply-templates select="@*|node()"/>
</xsl:copy>
</xsl:template>
<!--Remove all the VariableAssignment nodes-->
<xsl:template match="ait:VariableAssignment">
<xsl:comment>Removed VariableAssignment element</xsl:comment>
</xsl:template>
</xsl:stylesheet>
This transform is pretty dangerous, though, because it’s taking away all the VariableAssignment elements, and you might have valuable metadata stored that you would quickly blow away. So use with care.
This workaround is likely also useful for DITA and XHTML files, because Author-it outputs its DITA and XHTML files as UTF-16. I haven’t investigated its usefulness for those areas, but a quick search on the Author-it-users group on Yahoo revealed that sometimes people want UTF-8 rather than UTF-16. So, I hope this helps.
Categories: tools
Tagged: author-it, AuthorIT, DITA, identity template, software, techpubs, tools, UTF, UTF-16, UTF-8, writing, XML, XSLT
Our team is so excited for the new Author-it version 5.0 that we invited other Austin techpubs teams over to our office to watch the US & Canada webinar. It was like a movie premiere. Okay, we’re not really that big of dorks. But we had a good time with it.
By my calculations, it was about four AM Australia time but both the presenters were troopers, even when the typed-in license key didn’t “take” during the migration portion of the demo. All of us in the room empathized with her and she smoothly avoided any delays.
I’m mostly excited about the new interface. And Australians New Zealanders say “ribbon bar” so sweetly. It’s such a nice update. I’m really looking forward to using it. The organization of styles and templates makes sense as well, and I am glad to have separation between paragraph styles and character styles.
The search bulk-ups contain the features my co-worker was looking for - search within a folder and match case or whole word. Also the search within a topic as a customizable panel pop-out is going to be highly useful. That new editor interface is especially exciting. It reminds me of XMetal’s editing environment.
We can’t wait to start trying publishing profiles. We wanted to just start clicking in the dialog boxes displayed during the demo. Their knowledge base says that eleven profiles are shipped right out of the box (mapped directly to publishing outputs). The output types I see in version 4.5 are DITA, Word, PDF, HTML, XHTML, HTML Help, Microsoft Windows Help (RTF-based), Java Help, Oracle Help, XML, and Author-it Website Manager format. Since that list adds up to eleven types, I guess there are no new outputs with this release.
While we don’t currently have a use for Author-it Xtend, I found it fascinating as a concept. Why would a techpubs department pay money to a vendor for an embedded search engine to try to encourage writers to re-use? Why not just spend that money in training (or hiring) writers to think more about topic orientation and re-usability?
My co-worker pointed out that in a translation situation, Xtend might pay for itself in one translation round. It seems so very Google-like. There’s this sliding bar for more Fuzzy matches and more Relevant matches. There’s color coding for matches. I’m automatically drawn to it like a moth to a back porch light, yet I’m not sure of the best applications for the search hits nor what problem teams should expect to solve with this functionality. Perhaps someone can tell me the best scenarios for this add-on?
We copied the Questions and Answers from the webinar, and people asked plenty of questions. Here’s just a sampling - does 5.0 run on SQL Server 2005 (yes), does it run on Windows Vista (yes), questions about the new Project Manager (purchased as a separate module but is integrated into 5.0), is the 5.0 upgrade covered by a maintenance contract (yes), can you upgrade from 4.3 to 5.0? (yes), are presentations part of 5.0 (yes), and the final question was a good comparison: Can I use the Filters (Variables) on the Publishing Profiles as I would have used conditional build tags in RoboHelp to include/exclude content from specific output types? Am I understanding this correctly? The answer: yes, that’s correct.
So, exciting new features abound and we can’t wait to get our hands on them. I’ll keep you posted on our progress.
Categories: tools
Tagged: author-it, AuthorIT, CMS, content management systems, DITA, HTML, HTML Help, Java Help, Microsoft Windows Help (RTF-based), Oracle Help, PDF, publishing, robohelp, software, technical communications, technical writing, techpubs, tools, webinar, Word, XHTML, XML
September 26, 2007 · 4 Comments
Adobe has announced a Technical Communication Suite, combining FrameMaker, RoboHelp, Captivate, Acrobat 3D, and Flash, available in October 2007 for $1599 or $999 upgrade pricing if you already own one of the tools. This price point is well below what buying those products individually would cost (compare to $3600). I’m about a day late to the flurry of blog posts, as there are many bloggers commenting on this release, but many of them are focusing on the FrameMaker to RoboHelp single sourcing aspect, including the Adobe Technical Communication blog.
Scott Abel, The Content Wrangler, noted the price temptations, especially for people currently on RoboHelp. I’d just add that the upgrade price is the same price as Adobe Creative Suite 3 Web Standard ($999).
Dan Ortega’s message from Astoria appears to be but there’s no enterprise workflow and it’s a desktop solution, meaning, tech writers will still be the only users in a company using FrameMaker. Charles Jeter notes the same lack of collaboration in the suite in a nice wrap up post as well.
Sarah O’Keefe notes that most of her clients are going lighterweight than FrameMaker for their XML solutions.
Bill Swallow (techcommdood) notices that you can only go from Frame to RoboHelp, not back.
While single sourcing is always interesting to me, what I’m curious about are the use cases for Captivate, Acrobat 3D, and Flash, when using this Suite. I’ve used FrameMaker and RoboHelp in the past, but haven’t gone beyond the trial version of Captivate. So I looked at the webinar listing and there are hints at use cases that are an interesting sweet spot for the technical writer who wants to move past the static manual into interactive user assistance - not to mention the technical trainers looking for the correct tool to build interactive demos. Here are some catch phrases I lifted that might be just marketing-speak, but also might speak to where our profession is headed.
- track help system usage
- leverage existing content to create interactive help or performance support
- question randomization
- animation imports from PowerPoint
- do this cool buzzword stuff… without the help of your engineering department
So perhaps a key aspect of what Adobe has heard from tech writers all over is, we want to do cool stuff, but we’re not getting the resources we need to program the cool stuff.
And indeed, the webinar folks seem to want to help define where we’re headed and how we’ll get there. To quote from the intro paragraph, “What does this mean for technical communicators, instructional designers and eLearning professional today and tomorrow?” As go the toolset, so goes the career? I suppose that the skill demand certainly shapes what you learn as a technical communicator in order to stay employable. Does your software toolset make you do your job a certain way?
Categories: techpubs · tools
Tagged: adobe, captivate, Framemaker, robohelp, software, technical communications suite, technical writing, techpubs, tools
September 25, 2007 · 8 Comments
I thought I’d continue posting about my experience with Author IT since my initial review of AuthorIT. This past month I’ve been exploring ways to help out with the Author IT nuts and bolts, doing maintenance-type and infrastructure tasks such as changing the on-screen style formatting and revising a book template.
I’ve also been learning more about what is involved with the overall tasks of maintaining single source with nearly 20,000 objects in your library. Objects can be topics or books or hyperlinks or index entries or graphics or… many other items, so I’ll have to dig deeper to get a sense of how many topic objects we deal with daily. Ah, here we go - do an Advanced unqualified search filtered for results Of type “Topic Object” and then select the ones not marked “Obsolete” or “Orphaned” (meaning not used in a book object) and the answer is, we have over 7,000 topic objects in our library.
I maintain that the learning curve is steep but I’m fortunate (or sometimes unfortunate) that I’m approaching these tasks with an idea of how I think it might work. Plus I have an Author IT expert sitting in the office next to me who still answers my IMs when I ask Author IT questions. (Thanks, Mary!)
Changing the state
It is still taking me a while to get accustomed to the workflow that requires that I change the state of an object before making edits to it. If the topic I want to edit isn’t in a writeable state, then I can’t make my edits until I locate the object so I can right-click it to change the state. Maybe I’m missing some shortcut to how to change the state while editing a topic’s text. I’ll have to poke around the tabs a while. It’s more likely that I need to make a shift in my workflow and remember to select the topic objects I want to edit, change the state, and then begin the edits.
Search mechanisms
My understanding is that there are two basic search mechanisms and both are rather underpowered for the amount of legacy information we have stored. (I’ll have to get a topic count to give real numbers here.) The first search mechanism is searching the entire collection of topics and books and sub books. The Advanced Search checkbox is always checked in my environment.
The second search mechanism is on the actual text within topics - you can search for text within a topic, within a book, or within the entire library. This mechanism is found from the Edit > Find menu command in AuthorIT Enterprise Edition.
What I’ve found recently, however, is that you cannot replace formatting on the found items. This limitation means that you could have semantically tagged items that are not able to be retagged. For example, if you had tagged all your menu items as “menucascade” but needed to change the tagging to “breadcrumbnav” you would have to export the topics to an XML editor and do search and replace there. I don’t yet know how to batch export say thousands of topics to do this search and replace to get the semantic tagging you wanted. This analysis and potential workaround is based on searching within the Author-it Yahoo Group’s messages, so perhaps there is another way to search for text and formatting and change both the text and the formatting but I haven’t found it yet.
Even with these two search mechanisms at our disposal, we find it easier to use a Google search tool on our external database at docs.imis.com, then right-click on the HTML page to get the topic ID, then use that topic ID to search the AIT object database.
Author IT Yahoo Group
Now, I just went through the Yahoo Group messages again to learn more about the searches in AIT, and I really do like the community there. People are very helpful and still maintain a nice sense of humor and goodwill. That’s an important aspect of any tool selection I think. Anyway, there is a way to search within a set of found items, and that is to do a Search using the Search tab first, then press Ctrl+A to select all topics found that match the search criteria, and then do the Find and Replace command on the selected topics. That search also revealed a potential limitation of AIT’s inability to find period space space and replace it with period space (explanation of why period space is correct, because The PC Is Not A Typewriter).
A third search mechanism that we could make use of but that doesn’t yet exist would be the ability to search within a folder. We can use the trick mentioned above where you select all the objects in a folder then do a Find. A Folder in AIT is just a representation of the objects in a collection within a folder in the CMS of AIT (sorry, too many acronyms to qualify as a real explanation, but it’s basically another view of the database but not searchable within each Folder). But that’s a find on text, not a find on objects or metadata on those objects.
Variables to substitute text values
I find that the variable mechanism is a little bit clumsy. Variables are simply text enclosed in angle brackets <substitutethisforthat>. So you still have to do a search and replace for text when you want to choose a different variable name. If you use angle brackets in your documentation, AIT has to be told specially that you meant to do that and that those should not be resolved to a variable name. So, if you really want angle brackets to appear as angle brackets and not resolve to a variable, you have to use the HTML trick of ampersand lt semicolon.
Running AIT publishing from the command line
One nice feature is the publishing engine’s batch processing that will even output the commands for you so that you can include it in a batch process. We found that the outputs are always placed within the users folder that is logged in to AIT, despite using a documented command line parameter where you feed in a user and password for running the batch processing. Mary found a nice workaround where she just copies the files she needs out of another folder (the _Output folder in our environment), but it seems like a waste of disk space to me to have a second copy of output in each user’s folder. We can do some cleanup using the batch files to ensure that disk space is freed up, however.
Magical price point
Let’s face it, since it’s in the four figures for a seat license, Author IT is a relatively inexpensive all-in-one single sourcing tool that has both a straightforward editor and a content management system. A small techpubs department looks pretty darn good when they can deliver manuals and help as part of an automated build in a lights-off no-touch system. And the savings in translation costs when you single source are unmatched.
Where AIT “feels” inexpensive though, is in the slightly outdated interface (why can’t it remember the window size after being shut down?), somewhat underpowered search methods, and so far, I just can’t shake the general feeling that you’re not really owning or editing “source” files but rather some Word-like representation of the source.
Still, it works wonders and lets our small techpubs department output some high-quality professional content, more content than possible without a single-sourcing tool. So I’ll face the learning curve and continue to climb it.
Categories: techpubs · tools
Tagged: author-it, AuthorIT, CMS, content management systems, software, technical communications, techpubs, tools
September 20, 2007 · 3 Comments
I’ve been keeping an eye on the search keyword list for this blog. The hits are typically from search phrases like “technical writing” “masters degree” and “agile documentation.”
But one phrase that I found interesting was “just write what I say.” I would guess that the person is seeking voice recognition or speech recognition software, specifically verbal transcription tools. I suppose Dragon NaturallySpeaking is the first product that comes to mind, but there are OS-based options as well. I like their product’s tagline, “Turn talk… into text!” so props to them and a link.
Speech recognition can be integrated into certain programs on Windows XP SP1, such as Microsoft Word and Notepad, as this article from September 2003 describes, but you need Microsoft Speech Recognition Engine v5.0 and naturally, a microphone and hardware that can take in the speech sounds.
Mac OS X has speech recognition integrated as well, and you can even play chess with the computer giving it voice commands, according to this web page.
So, I’m writing this post to gather some traffic but offer useful information while collecting those hits. Give back, I say. Let me know if you found this information useful.
Categories: tools
Tagged: accessibility, software, speech, speech recognition, tools, transcription, voice, voice recognition
In my previous post, I interviewed Diane Fleming who had completed a graduate degree in technical writing later in her career. Today’s interview is with Melissa Burpo, who has completed the coursework and internship portions of the graduate program but still needs to write up her internship report (an equivalent assignment to a master’s thesis) before graduating. I was especially interested in the most current graduate’s perspective and Melissa graciously agreed to answer all these questions.
Melissa Burpo’s Interview
Anne: Could you give me a little bit of a bio - your employer, how long you’ve been there, what you do there?
Melissa: I work for Dovetail Software (www.dovetailsoftware.com), a CRM software vendor. Before I was hired as an intern in October 2006, Dovetail had never employed a writer of any sort, and I had never been employed as a fulltime technical writer. Because both the company and I are new to this whole “technical writer” thing, my job duties can be somewhat nebulous. Common tasks include rewriting, reorganizing, and redesigning legacy documents; writing end-user documentation for new functionality alongside a small agile development team; and lately, moving all of our scattered documents into AuthorIT, a single source content management system. I also occasionally handle marketing tasks, such as writing, designing, and voicing product demonstrations; designing product and company brochures; and producing graphics as needed for other marketing purposes.
Anne: First of all, tell me what your undergrad degree was in?
Melissa: Bachelor of Arts in Communication from Oglethorpe University, with a minor in Sociology
Anne: What led you to a graduate degree in tech comm?
Melissa: An undergraduate professor suggested that I look into tech comm after I finished my bachelor’s degree, but it took me three years to find my way to the MTSC program at Miami University. At first, I was turned off by the idea – I thought tech comm meant writing instruction manuals all day. Eventually I figured out that there was a very cool side to it as well – tech writers are constantly learning new things, exploring new technologies, and then figuring out how best to communicate that information to a user base. It seemed like a fun and innovative space to work in, so I decided to get the degree.
Anne: What other degree programs did you consider?
Melissa: I briefly looked at degrees in Professional Writing and Literary Nonfiction, but tech comm won out in the end.
Anne: What did you learn in the degree program?
Melissa: I learned how to practically apply technical writing theory to real-world problem solving contexts. Almost all of my school projects were for real clients in a variety of industries. For example, I collaboratively put together a website for a waste water group, wrote and designed a procedural reference card for nurses at a local hospital, and wrote a white paper about a local environmental issue for the university.
Anne: What do you wish others had told you about technical writing before you got a job in it?
Melissa: I wish someone had warned me that being a technical writer is just as much about building successful interpersonal relationships as it is about writing and designing good documents. Forging a good relationship with your SMEs is vital, because they are your information resource. Everything works a lot better if he or she is happily willing to share information.
Anne: What do you consider to be the “value” of the graduate degree - in monetary terms, employability terms, and general learning?
Melissa: I don’t see the value as the degree itself, but instead, I see the value as the experience I gained while in the program. The experience translates into a full portfolio, a well-rounded resume, and the ability to find and secure a good job.
Anne: Do you think the degree has paid for itself?
Melissa: Yes, absolutely.
Anne: How well has the education “aged,” meaning, are the subjects you studied still current for the field?
Melissa: So far, so good – of course, I’ve only been out of the program for a year : )
I do want to mention one thing, though. The technology I studied has already been replaced by new versions and new innovations. But that’s okay, because one of the greatest lessons I took away from my program is the ability to quickly learn new technology as needed.
Anne: Do you think that an undergraduate degree in tech comm offers the same results as a masters degree in tech comm?
Melissa: Yes. If the undergrad degree has a practically-based curriculum that prepares students for a professional career, then there shouldn’t be much of a difference. I needed the graduate program because my undergraduate degree was unfocused. It didn’t prepare me for a career.
Anne: If you hadn’t gotten the master’s in technical and scientific communication, speculate about what might be different for your career path and job prospects.
Melissa: In the one year since leaving the program, I’ve already completed two contract jobs and an internship, and I now work in a regular full time position. I don’t think any of this would have been as easy or possible without the experience I gained in my graduate program. If I hadn’t gotten my MTSC degree, I would probably still be struggling to establish myself as an employable, valuable professional.
Anne: What would you advise others who are thinking about pursuing graduate work in technical communication?
Melissa: When looking for a program, find one that gives you practical experience in the field. This will not only start you off with a great portfolio, but it will also give you the knowledge and confidence to move into a real job. Also, keep in mind that studying a specialty area is important. For example, if you want to work in the pharmaceutical industry, you’ll probably need to know something about human biology, drug chemistry, regulatory issues, etc. This should be reflected in your studies, whether it’s before, during, or after you enter the tech comm program.
Categories: techpubs
Tagged: education, graduate degree, graduate program, graduate school, higher education, interview, jobs, MTSC, portfolio, ROI, scientific communication, technical communication, techpubs, tools, undergraduate, value
It’s no secret that I have a masters degree in technical and scientific communication from Miami University. With all the hype about Web 2.0, outsourcing, crowdsourcing, and social media like wikis, an interesting question that I get asked occasionally is, “should I get a graduate degree in technical writing?”
I’ve had quite a few interesting online discussions while seeking interviewees, and I’ll post two interviews this week, and then try to discuss all the complexities in answering this question in a third post.
I emailed questions to two current technical writers in the Austin area who have masters degrees in technical writing. This first post is an interview with Diane Fleming, a Senior Technical Writer at NetQoS. The second interview is with Melissa Burpo, a not-quite-graduated degree candidate who’s working as the only technical writer at DoveTail Software.
Diane Fleming’s Interview
Anne: Could you give me a little bit of a bio - who is your employer, how long you’ve been there, what you do there?
Diane: I currently work as a Senior Technical Writer at NetQoS. I provide all documentation for SuperAgent, an end-to-end performance monitoring tool. Because the Training and Technical Writing departments are combined at NetQoS, I provide product docs (pdfs and online Help) and curriculum for customer training.
Anne: First of all, tell me what your undergrad degree was in?
Diane: It’s a BA in English from SUNY Buffalo.
Anne: What led you to a graduate degree in tech comm?
Diane: I had never heard of technical writing as a profession (this was in the late seventies), but a graduate of RPI’s technical communications department offered a one-night seminar at a local college entitled, “A Career in Technical Writing.” After taking the seminar, I discovered that a high school friend of mine had also graduated from RPI, so I started exploring their degree program. At the time, I was working at the Poughkeepsie Journal and they had a very open tuition reimbursement program. They agreed to pay for my degree at RPI, though it required that I work full-time and commute to Albany to complete the degree (a two-hour commute in each direction).
But I couldn’t pass up the free tuition.
Anne: What other degree programs did you consider?
Diane: None, though later I began work on an M.S. in computer science (which I never completed).
Anne: What did you learn in the degree program?
Diane: I don’t remember the exact titles of the classes, but we learned writing and editing, project management, and computer programming. One of the classes required that we work as a team to produce a piece of documentation, which unfortunately required an extra weekly commute to Albany for me. We also took a communications
class, which entailed a general review of communication theory.
Anne: What do you wish others had told you about technical writing
before you got a job in it?
Diane: I’m not sure anyone could have told me, but I always regretted not pursuing computer programming in lieu of writing because of the greater respect programmers garner – tech writers have to constantly remind others of their value. Sometimes it seems like a losing battle. With offshoring, the message seems to be, if you can speak English, even minimally, then you can be a tech writer!
Anne: What do you consider to be the “value” of the graduate degree — in monetary terms, employability terms, and general learning?
Diane: My degree opened a lot of doors for jobs I’d otherwise be overlooked for. I’ve managed to stay employed as a tech writer since 1988, and I’ve been paid well.
Anne: Do you think the degree has paid for itself?
Diane: Absolutely! Especially since my employer paid for the degree. Even if I had paid for it, the degree was worth its cost. It’s enabled me to put two sons through college and to support my family.
Anne: How well has the education “aged,” meaning, are the subjects you studied still current for the field?
Diane: The skills that have aged well are writing, editing, and project management. But as technology changes, my skills degrade. New programming languages, wikis, agile development, blogging, browser-based interfaces, so on and so forth – all these innovations require that I keep learning new things to stay current.
Anne: Do you think that an undergraduate degree in tech comm offers the same results as a masters degree in tech comm?
Diane: Probably. When I got my M.S. degree, lots of teachers were retraining to become technical writers. In fact, the original program at RPI was geared toward teachers. RPI ran summertime institutes so that teachers could retrain during their time off. The masters degree enabled people in other professions to retrain in a couple of years. But for someone coming right out of high school, an undergraduate degree should suffice.
Anne: If you hadn’t gotten the master’s in technical and scientific communication, speculate about what might be different for your career path and job prospects.
Diane: I doubt I would’ve become a tech writer – I’d tried to “break into” IBM for many years – it was the major employer where I lived, even minimally, then you can be a tech writer!
Anne: What do you consider to be the “value” of the graduate degree - in monetary terms, employability terms, and general learning?
Diane: My degree opened a lot of doors for jobs I’d otherwise be overlooked for. I’ve managed to stay employed as a tech writer since 1988, and I’ve been paid well.
Anne: Do you think the degree has paid for itself?
Diane: Absolutely! Especially since my employer paid for the degree. Even if I had paid for it, the degree was worth its cost. It’s enabled me to put two sons through college and to support my family.
Anne: How well has the education “aged,” meaning, are the subjects you studied still current for the field?
Diane: The skills that have aged well are writing, editing, and project management. But as technology changes, my skills degrade. New programming languages, wikis, agile development, blogging, browser-based interfaces, so on and so forth – all these innovations require that I keep learning new things to stay current.
Anne: Do you think that an undergraduate degree in tech comm offers the same results as a masters degree in tech comm?
Diane: Probably. When I got my M.S. degree, lots of teachers were retraining to become technical writers. In fact, the original program at RPI was geared toward teachers. RPI ran summertime institutes so that teachers could retrain during their time off. The masters degree enabled people in other professions to retrain in a couple of years.
But for someone coming right out of high school, an undergraduate degree should suffice.
Anne: If you hadn’t gotten the master’s in technical communication, speculate about what might be different for your career path and job prospects.
Diane but at the time, I was told that women were secretaries and that was that. I had worked as a temp secretary at IBM, even with an English degree. It wasn’t until I received my masters degree that someone would interview me for a tech writing job at IBM. I might’ve eventually pursued a computer science masters degree in order to become a programmer. But if I hadn’t done that, maybe I’d still be at the Poughkeepsie Journal doing graphic design for retail ads.
Anne: What would you advise others who are thinking about pursuing graduate work in technical communication?
Diane: Check out certificate programs first – RPI offers a HCI certificate (human-computer interaction), which might help you find work as a tech writer. Also look into current technologies – are companies using wikis? What kind of technical information do you want to document? If you’re interesting in writing about programming interfaces, you might get an M.S. in computer science to complement an English degree – this might be of more value in the long-run in terms of pay scale and promotability. Also look into distance learning – schools offer low-residency programs in technical writing, which enable you to keep working and pursue your degree at the same time. Also look for a program that’s tied into a particular industry. RPI was associated with IBM, which really enhanced their program. I think more academic programs are less useful. If the program seems to focus on a lot of theory, it’s probably not going to help you be a good tech writer, though it might help you teach. Also, see if you can talk to a tech writing manager at a local company and ask them what they recommend to become a tech writer.
Categories: techpubs
Tagged: education, graduate degree, graduate program, graduate school, higher education, interview, jobs, portfolio, Rensselaer Polytechnic Institute, ROI, RPI, scientific communication, technical communication, techpubs, tools, undergraduate, value
I’m now writing in an AuthorIT environment. My first learning task is to find out the proper pronunciation, is it Author Eye Tee? Or Author It? Let’s see what wikipedia has to say about AuthorIT. In their article, they consistently refer to the product as Author-it, so I would suppose the second pronunciation I proposed is the correct one. Plus, the AuthorIT website has Authorit throughout. Internally we call it AIT for short.
At first glance, the product looks and feels like a database-centric content management system because of the initial connect you make is to a SQL Server database. But in fact the way you browse the system is folder-based, as if I were using Windows Explorer. So far, so good, except that I’m not yet completely familiar with the way that the CMS folder structure is set up based on our Function-based teams. However, we have a Helpsite that lets me browse the current content in another way and has a decent search mechanism and index to allow me to look for the topics I’d need to update.
What I’m doing now to get started as a greenhorn with both the toolset and the product I’m documenting is to peruse the Helpsite which is organized by tasks and features of the product, and then determining what topics need updating for the particular feature I’m working on, and then right-clicking and getting Properties on the page I want to update. Next, armed with the five-digit number that the HTML file is named, I do a search in the AuthorIT database to find that exact topic, and then make my edits. Whew.
One incorrect assumption I had going in to the AuthorIT environment was that editing is all based in Microsoft Word. Not true at all, my AIT trainer protests, the editor is AIT’s own, but AIT does a good job of outputting to Word formats and you can use VB macros to format the output as you wish. I’m still learning so I’ll let you know what other incorrect assumptions I’m finding otherwise about.
The other thing that strikes me right away is that while it’s topic-based and structured authoring, all the things you create are either books or sub-books. I wonder if that interface could be changed to refer to deliverables or some other such generic term that isn’t loaded with a print connotation. It’s a minor nit to pick, that the loaded term “book” is so prevalent, but many other editors and CMSes have gone beyond the book terminology so I was surprised it still lives in AuthorIT.
To be perfectly honest, I wasn’t all that impressed with the available outputs. Here’s the list from the AuthorIT website: (hey, I would have given you all a more precise link, but when I clicked Publishable Outputs in the sidebar in that page, I got a page not found error using IE 7 on WinXP SP2.)
Publishable Outputs
Print
- Printed Documentation (Word, RTF, or PDF)
Help
- WinHelp
- Microsoft HTML Help
- Sun JavaHelp
- Oracle Help for Java
- Vista Help (Upon Release)
Web
- Web and browser based Help
- HTML 4.01 + CSS (W3C Validated)
- XHTML 1.0 + CSS (W3C Validated)
Presentation
- HTML based slide show Presentations
XML
The first omission that comes to mind is the lack of Eclipse help output. There’s also no Flash help output. In addition, I wanted to analyze further on the usability and look and feel of the Web and browser based help, especially with the recent article complaining about DITA’s lack of a cross-browser “Web help” like what Robohelp outputs as well as the lack of FlashHelp output. There are a couple of good articles out lately about it. There’s an article on ditausers.org comparing Help Authoring Toolkits to the DITA Open Toolkit. His output comparison matrix for DITA points out the lack of a webhelp equivalent for DITA Open Toolkit transforms. Here’s Tony Self’s recent analysis on Writer’s UA website. But I’m not talking about DITA necessarily, unless I was going to propose outputting AuthorIT to DITA and using DITA transforms for publishing, a workflow that I’m not proposing because it just seems too roundabout and more difficult to automate.
Anyway, my first glance at the AuthorIT web help output is that it’s a little bit antiquated but it is tripane and it does have contents and index tabs but no search tab according to the demo on the AuthorIT site. Frankly, without a search function, no help system is complete. With a quick Google search, though, I learned from Char James-Tanny that “by default, AuthorIT does not include a search tab, although the Help file does include instructions for hooking up a free CGI search.” That article appears to be dated January 2003 so I would have to do more hands-on testing to determine the quality of the search and the ease to implement it. Interestingly, in that article she mentions using AuthorIT as the CMS and editing environment and then using RoboHelp for the more feature-rich output engine. I wonder if that’s still a viable toolkit and publishing engine combination now that Adobe is developing RoboHelp.
Writing an article like this one while I’m still very inexperienced with AuthorIT is risky because I will read it later and think, “why would I proclaim my ignorance in a public manner?” But I believe it’s important to capture initial thoughts and reactions while they’re fresh in my mind. So bear with me while I analzye the authoring system and the publishing system and draw some perhaps premature or immature conclusions.
Categories: tools
Tagged: , author-it, AuthorIT, DITA, software, techpubs, tools, writing
Anne is a senior technical writer at Advanced Solutions International. Read 
