Posted in Uncategorized

Confessions of a Failed Technical Communicator

homer_confession
Really, Father, my only sins are beer, donuts, beer, donuts, not knowing DITA, beer, donuts…

“Bless me, Father, for I have sinned! I am a failure in technical communications.”

OK, perhaps in many eyes, I haven’t been a failure in technical communications. It will be five years this spring since I graduated with my Masters degree in Professional and Technical Communication from NJIT. In many ways, that feels like it was just yesterday, and I’m still a “new graduate”. But with the change this year in my STC Membership that’s moved from “Student” to “New Professional” to “Classic”, I supposed I’m not anymore.

While graduate school gave me a good foundation to move forward, I learned very quickly that I needed to continue to educate myself. As I attended conferences and presentations, and paid attention to discussions in social media, I found out that graduate school lessons barely cut the surface. I’ve tried my best to continue my studies by attending as many webinars, conferences, and presentations that I can. I even took another university graduate certificate course on digital marketing, hoping to get some insight that might help me going forward.

However, in the end, I failed to do one thing that might actually boost what I’m doing as a fledgling content strategist, and thus, my confession: I needed to learn DITA.

For those of you who don’t know what DITA is, it’s the acronym for Darwin Information Typing Architecture, and it’s a commonly used method for creating structured authoring using XML coding. The idea is that documentation done using DITA methods will allow for single-sourcing for content elements, and equally make it easier to integrate that content into print or digital outputs in a super-organized, modular way. It’s a standard that helps because it’s generic to almost any system out there. Any system that can read XML can read a DITA document, for the most part. When moving from one system to another, the content can stay intact if done using DITA/XML methods.

I don’t remember learning much about DITA in grad school, other than understanding what it was in general as I explained it above. I never learned the details. In my work life so far, I haven’t needed it.  It’s always been unstructured authoring. I try to take some small steps to create some single-sourcing content when possible in content management systems, but that was hard to do sometimes. One of my recent jobs made me realize that we needed some sort of structured authoring done, but I didn’t know how to go about it. We created our own coding tags to describe things going on in copy decks. It wasn’t the best, but it was better than nothing.

In the past year, I’ve tried to figure out ways to continue to improve my skills, and make myself more marketable as a content strategist/content manager. I talked to the leading experts in the field. (It’s one of the benefits of getting involved with the STC and attending STC events–you get to know these people personally.) And the one thing that seemed to come back to me again and again was that I had a good resume, and I have some great skills under my belt, and they knew that I was a good writer from this blog. The biggest sore spot in my skill set was that I lacked an important skill–knowing DITA and using it.  And while I looked for jobs in my area that included DITA practices (I think I’ve only seen one listing in three years), I’ve been assured that if I could learn DITA, the remote/telecommuting possibilities could be much better for me. And since remote opportunities are my best bet right now, I have to do what I need to do to make that happen.

So, as the saying goes, I bit the bullet. Fortunately, the STC was promoting a course about DITA Essentials taught by Bernard Aschwanden, the Immediate Past-President of the STC, and the proprietor of Publishing Smarter. Bernard’s a great instructor, and he’s taking it nice and slow. One of the best parts of the course is hands-on experience, even if it’s in the simplest ways. That’s the way I tend to learn best–learn the logistics of how something is done, then I need to learn to do the work through trial and error.  Last week’s assignment was particularly challenging for me. While I understood what I had to do conceptually, since I was also trying to familiarize myself with a few XML editors at the same time while applying what I wanted to do with my assignment, I got very frustrated. I sent in my assignment, along with notes about where I was getting frustrated and needing some guidance. Bernard assured me that all would be well, and asked me if he could use what I had turned in for my assignment for the most recent class. He also warned me to have a glass of wine ready while taking class, because I’d be needing it. Yikes!

I was told to prepare for the onslaught of big corrections to my DITA homework with a glass of wine. I took the suggestion seriously, thankfully.
I was told to prepare for the onslaught of big corrections to my DITA homework with a glass of wine. I took the suggestion seriously, thankfully.

The glass of wine was done by the end of the class, and yes, he ripped my assignment apart, but it was okay in the end. I knew there were problems with it, and he showed me where my original thought process was correct, but I didn’t know how to execute it properly. One of the mistakes I was making was my use of XML tags, particularly using the correct ones. While the XML editing apps all have guidance features to help you with using correct tags in certain situations, I still wasn’t using the best choices. Most of that was because I’m not familiar with what these XML tags mean, so I was using them at face value. For example, I was using a step example tag in part of my content, and Bernard understood why I used it, but felt that the way I used it was incorrect, and didn’t allow for cleaner coding. Okay, I can deal with that, especially when he demonstrated the correction.

So, as much as I’m struggling with DITA, I do understand the essential concepts behind it now. My biggest problem is learning how to use it beyond the most elementary tasks. I haven’t had any “real world” scenarios to date when I could implement and learn how to use the XML editors and use DITA practices in writing or rewriting content.  I need to figure out how to find content and start having a way to truly play with something so that I can get the full experience of that trial and error to master DITA.

After the STC course that Bernard is teaching, I plan to follow-up with Scriptorium’s DITA tutorials as well, and see if I can learn some more about XML coding. I have a lot to do to figure this out, but I know that in the end, this will be a big skill that will make a lot of difference in how I approach content. The content strategist skills I already have acquired have helped me frame DITA much more easily than if I learned this with no prior knowledge. But, I can tell that I still have a long way to go before I feel that I’ve mastered this.

So, this ends my confession. I have needed to learn DITA.  If it’s not taught in university classes in technical writing, it should be. I think it would have saved me a lot of frustration, and provided more opportunities for me sooner. If I can get a better handle on this, I’m hoping that I can start exploring how XML Editors can integrate with CMSs, like Adobe CQ. I’m not an Adobe AEM developer (I’m not a developer at all!), but I know how to create websites and pages with AEM, and hopefully I can start figuring out how to integrate those skills with DITA skills. I was told by one mentor, that would make me a very desirable job candidate, and I think she’s onto something. Of course, I need to brush up on my AEM skills, since it’s been a couple of years since I’ve used them regularly, but with all things, once you master them, it’s like riding a bicycle. You might be a little unstable at first, but you never quite forget how to do it once you get started back into it again.

Here’s hoping that in 2017, DITA will become a “bicycle” skill for me. I’ll go say a few rounds of the Rosary in the meantime for my penance.

(What do you think? How important is DITA in technical writing? I’ve heard some say it’s a passing trend, and others say that its usage continues to grow. Include your comments below.)

Posted in Uncategorized

A New Year–A New Adobe Technical Communication Suite – PREVIEW

TCS5-Ball-Drop
The Times Square New Year’s ball drop has landed…it’s a new Adobe Technical Communication Suite!

As of TODAY, Adobe is releasing five new tools for technical communication professionals everywhere! Technical Communication Suite 5.0 (TCS5), FrameMaker 12 (FM12), FrameMaker XML Author 12 (FMXA 12) and RoboHelp 11 (RH11), and FrameMaker Publishing Server 12 (FMPS12) are now available. It’s been about eighteen months or so since the last big Adobe tech comm release, so you can imagine there are some new and enhanced features included.

I was privileged to be among a group of tech comm professionals who were invited to get a preview of the products before their release, and I have to say, there were so many new and improved features that it was difficult to squeeze all the information into one press conference! But I’m going to give you the highlights, and I’m sure you’re going to find that there’s something new for you.

In the last release of TCS, namely TCS4, there were several big overhauls of the product, namely that the Technical Communications Suite concentrated on providing tools that supported structured authoring, integrated interactive content, and could support the creation of content for mobile devices while providing searchable, personalized, socially enabled content in a way that would yield bigger results with less resources. It was a major step to enhance these tools, especially in regards to adding mobile and interactive abilities to content. Adobe has continued to build on those major changes with the new features in version 5.0.

The foundation of the Tech Comm Suite has always been FrameMaker and RoboHelp. With the release of TCS5, FrameMaker 12 and RoboHelp 11 have been released with big enhancements that appear to concentrate on making these tools more user-friendly and efficient for the technical writers using them.

FM12_boxshot_2014
Image courtesy of Adobe.

For FM12, the first obvious enhancement is the interface. Adobe has improved the user interface to include colored icons and larger icons that look cleaner and sharper in HD. If you like things “old school” in the original smaller, monochromatic colors, that choice is still available as well. There is also more flexibility in customizing your interface. A new “pod” allows the user to access all the currently opened files in one place, from which you can save and close multiple files at one time, while still viewing the unsaved files. There are also enhanced abilities to drag-and-drop to empty areas of the interface, close pods or panels more easily, double-click on empty areas to minimize or expand pods, and searching capabilities have been expanded. These seem like minor details, but when using a product as often as many technical writers use FrameMaker, these finer details can make a big difference! FM12 includes three samples of unstructured content and one DITA-based content sample with the product.

FM12 is not all about a new façade. Adobe has enriched the authoring process with new capabilities. The first thing that caught my attention is that FM12 can generate QR codes now! They can be created for URLs, SMS texts, emails, or to initiate phone calls. QR codes are taking over these days, so it’s great that these can be both created and integrated into FM documentation. Background color enhancements allow uniform height background color and options to specify paragraph boxes. The addition of a new customer-requested feature is the support regular expression coding.

Single-sourcing has been a hot topic in the last few years, and this has been addressed with new enhancements. FM12 gives users a new way to work with conditional text, by using a new conditional tag pod which provides check-box mechanisms with multiple conditions to allow the user to do more complex filtering with conditional text enhancements. It truly simplifies the entire process, that even a newbie should be able to figure it out easily.

Productivity enhancements have also been included in FM12. A searchable smart catalog function allows the user to filter choices based on the valid choices available and phrase typed by the user, while the user can continue to use the keyboard shortcuts as before. There is also a new capability to open all files from the user’s last session in one click, including the last documents and pages in focus, workspaces such as pods, panels and palettes, among others.

Adobe has also taken care to add great collaboration enhancements in FrameMaker. Native connections to any webdev content management system (CMS), such as Documentum, SharePoint, and Adobe CQ are available. Users can now view entire CMS tree layouts, and can access several key CMS functions, such as checking out documents, editing documents, and searching within document, all from FM12.  PDF review commenting has been made more flexible. The most proactive steps towards subject matter expert (SME) reviews is that reviews can be done on PDF reader apps on mobile devices, and can also be used on those same devices using cloud technology such as Dropbox for both internal and external reviewers. As mobile devices become more commonplace replacing desktops and laptops, this is a great step forward!

Image courtesy of Adobe
Image courtesy of Adobe

Publishing abilities have gotten a boost on FrameMaker as well. It used to be that if you wanted to create certain types of digital output, such a ePUBs, for FrameMaker content, you would have to export it to RoboHelp, and have RoboHelp publish the document.  Now, that step is no longer needed for PDFs, Webhelp, ePUBs, Kindle docs, Microsoft HTML Help, responsive HTML5, or Web help! That’s a big deal, as it allows FM12 to be more efficient by skipping that step of exporting and publishing in RoboHelp. Publishing can also be done through the Web now, too, for multiple users using a FrameMaker server, allowing multiple users to publish simultaneously and automatically to multiple channels and devices. That’s a practical efficiency improvement right there!

FMXA12_boxshot_2014
Image courtesy of Adobe

With this release, Adobe is introducing a new FrameMaker product for those who don’t need the full version of FM12, but are mostly concerned in having a tool to do structured XML authoring. FrameMaker XML Author is a tool that has been created especially for the structured XML market.  Those wanting to use unstructured content will still need to use the full FM12 version.  The XML Author is fully standards-compliant for content creation, and supports the most popular XML technology for single-sourcing. It is not FM12 “lite”, but it is a streamlined, easy-to-use version that supports structured authoring without the bulk of the FM12 features that aren’t needed for structured content, yet still integrate-able with the full version of FM12 and available at a lower price. I’m sure that having this tool will be highly beneficial to many companies who are looking for a way to cut costs (it is priced at 40% the price of FM12 “full”) while still reaping the benefits of having a powerful XML authoring tool.

Another customer request that has been granted by Adobe is the integration of MathML, to allow MathML equations to be imported, created, edited, and published with FrameMaker. Adobe is even including 30-day trials of MathFlow (MathML editor from Design Science) with the shipment of FM12 for those who are interested in trying it out. There are several other features that are also included, along with 55 bug fixes, improved performance and launch time for FrameMaker, but I’d end up writing a book at this point!

Of course, with all these big changes to FrameMaker, we can’t forget RoboHelp 11, which also has had a big overhaul.

Image courtesy of Adobe
Image courtesy of Adobe

RH11, like FM12, has a new UI look as well. Based on customer feedback, RH11 has a new color scheme and a more modern interface that looks more pleasing to the eye. It’s a step in the right direction. Adobe has said that further UI improvements are in the works, but this current new UI is the first step in a long overdue makeover for the interface.

The more important feature enhancements with this new release of RoboHelp include advances with HTML5 publishing, printed document enhancements, and collaboration and single-sourcing enhancements.

The HTML5 publishing enhancements are from the perspective that mobile publishing is central, so new single responsive layouts for all devices are available “right out of the box” when downloading RH11. This new single layout feature will work seamlessly across all devices, can be easily customized, will allow for real-time previewing based on the browser size, and can be published with one click.  There is a new wizard-based layout editor available to help with this process that shows the added responsive HTML5 output options. You can also preview layouts, and the customization is great because no coding in CSS needs to be done, as you can use the editor instead.  To me, this is true single-sourcing creation at its best while simplifying the process! This is a big deal!

Printed documents have not been ignored. Users can now customize headers and footers of printed documents by defining them in the master pages. Headers and footers can also be imported from Word. There is also the ability to specify different headers and footers for the cover, and even and odd pages for different sections of a document. This is great for consistency within branded documentation.

In terms of collaboration and single-source improvements, cloud integration and topic sharing for SMEs has now been included.  RH11 now includes a Resource Manager tool that synchronizes folders using Dropbox, Google Drive, or Microsoft SkyDrive as shared locations, and includes filtering for specific folders. This allows the user to manage linked resources within files used in real time across projects and geography.

Image courtesy of Adobe
Image courtesy of Adobe

The Technical Communication Suite 5.0 includes FrameMaker 12 and RoboHelp 11, but it also includes the updated products of Acrobat Pro XI, Captivate 7, and Presenter 9 to complete the Suite. You will notice that Illustrator, which was included in the TCS4 version, is not included. This was a step, Adobe said, to help lower the price. Additionally, from the way I see it, it makes sense, because both Illustrator and Photoshop–another product that used to be included in prior TCS versions–are now affordably available as part of the Adobe Creative Cloud subscription. I know that I personally have a CC subscription, and I’m guessing that many active technical communicators do too, so this saves us from spending twice for the same product, which makes a lot of sense. TCS5, FM12, RH11, FM XML Author, and the FMPS12 will also be available both as a subscription and through perpetual license as well. There is separate pricing for the FM XML Author and FM Publishing Server software.

The updates made to FrameMaker and RoboHelp are extensive, as there are many more features, but I think you get the idea. Adobe is taking steps to try to stay on top of technological changes that have taken root in the past couple of years, such as mobile and cloud technology, and is working to continue to make a more robust and user-friendly products for technical communicators.

My recommendation is that if you are looking to try TCS5 or any of the TC products out, or are interested in upgrading your current TCS package or individual products, click on the Adobe advertisement in the upper right corner of this page, or visit Adobe’s TCS product page for more information.

I hope you find this helpful!