Technically Speaking

As  a “young” technical writer, I thought I might share some of my feelings on the STC crisis.

First, a little background on me. I knew while I was in college that I wanted to be a technical writer after graduation. I switched to an English major for that purpose, and picked classes that gave me a “technical communication emphasis”. I joined STC while I was in college because I wanted to connect with people in my field. I got a chapter scholarship to attend a regional STC conference, and had a great time meeting people who did for a living what I was studying.

When I graduated and began working, I joined STC as a regular member. For two of my three jobs, I had to explain to my employer what the “STC” bullet meant on my resume. Until my current job, I’ve never had an employer who would pay for conferences, so my interactions with STC have been limited to those in the local chapter, on the web, and through STC publications. I believe herein lies the problem that STC faces: STC’s value proposition has to be able to compete with what I can obtain from other sources, and do so in a compelling way.

I look at it this way: if the STC were to go away, what would I lose? Let’s take a look at the benefits that I care about that I’d lose:

• STC publications. I like receiving Intercom. I honestly don’t really ever read Technical Communication. I get the need for a peer-reviewed journal, and understand how this is especially important in academia, but the stuff in TC generally doesn’t seem to interest or affect me. But the reality is that most of the articles that are published in Intercom would get published in other forms (like blogs). They might not be on the same subject, but the information is out there, and will continue to be churned out by writers like my colleague Tom Johnson who are better bloggers than I. So, if the publications go away, I’ll miss them a little bit, but not a lot.
• Local chapter affiliation. I’ve not been very active in my local chapter until the last couple of months. I’ve attended a couple of meetings in the 5 years that I’ve been a member, but let’s be honest: like any professional, I’ve got lots of things competing for my time and attention. I have a young family that I really enjoy spending time with. When STC meetings conflict with personal interests, I’ve picked personal over professional because I haven’t seen tons of value in the local chapter. My perspective on that is changing as I’ve accepted a VP position in my local chapter, and I hope that as an executive team, we can find ways to make our local chapter more useful to the technical communicators in our region. Six months ago, I considered not being affiliated with a local chapter, but now I’m finding more value there. Maybe this is a resource like so many others that you get out of it what you put into it.
• SIG / STC online affiliations. The SIGs haven’t been really useful to me. I’m a member of one SIG that has never contacted me with information about the SIG; has never provided any information about lists I might join, nor provided any other benefit. The other SIG has a mailing list, but it isn’t the most active list I follow, and the questions that get posted to that list might as well be posted to other non-STC lists I follow. I’ve watched some STC community leaders create other online sites that don’t restrict their membership to STC members, but they promote these sites to STC members. I think STC loses value in these cases, because I might as well join the other groups (for free) than pay to be a member of STC.
• Salary survey. The salary survey on STCs website is now a complete joke, and I find it useless. I preferred the old method of self-reporting. While less accurate, I found it much more helpful than the current salary survey. I won’t miss this resource at all because I don’t use it. There are several salary websites I can use that provide as much, if not more, value than the STC salary survey.
• Job resources on STC websites. The jobs section of the Society web site has not been a useful tool for me. When I’ve been looking for jobs, there haven’t been any local listings. When I went to post a job, there was an additional $120 fee, which my employer wouldn’t pay because they were already listing on Dice and Monster. The irony is that we were able to post on the local chapter website for free, and the writer we hired found us through the local chapter listing. So without STC’s local chapter website, we wouldn’t have found that writer, but it’s not like there aren’t other job boards that tech writers and their employers are using.

So here is my question: if STC is going to remain a viable organization, what is going to be the value proposition? What will STC provide that I can’t get from other sources? And then I have to ask, how much is that worth to me? I hope STC focuses on what I can’t get elsewhere and does it in a way that is valuable and interesting. That is what will keep me, a “young” writer interested in the organization.

According to MadCap’s website, MadCap Flare V5 is now available for everybody! If you have a maintenance agreement, I guess that means you can expect your Flare V5 license to arrive shortly!

If you want to know more about what is coming in the latest version, check out my pre-release blog post.

Soon MadCap Software will be releasing the next major version in the Flare product line, Flare V5.

I’ve been beta testing Flare 5 for a couple of months now, and there are some great new features in Flare 5 that you are going to love. In this review, I want to point out some of my favorite new features, as well as some of Flare 5′s other great enhancements.

Let me begin by saying that I love Flare, and I think Flare 5 is a great enhancement on an already great product. I am biased; I’m a certified Flare instructor, have been a VIP in the Flare Forums for 2+ years, and am a certified MadCap Advanced Developer for Flare V4. But being biased doesn’t necessarily make me wrong <grin>. I’m under NDA for this project, but I’ve received permission to give you a preview of what you can expect from the soon-to-be-released version 5.

Here are five killer reasons you should consider upgrading your version of Flare to V5 as soon as you can:

1. Workspace improvements in both XML Editor and Source Code View
2. DITA Support
3. PDF Target Enhancements
4. Relationship Tables

5. Other Enhancements
   – Topic Tool bars
   – Thumbnail Image Support
   – Text Redaction Support
   – Improved Performance
   – Conditions in Project Organizer
   – Backup Differences
   – New Toolbar buttons

I’ll discuss each of these features in the sections below.

Workspace improvements in both XML Editor and Source Code View

Flare 5 sports a spiffy new code editor with line numbers, color-coded tags, and easy access from the XML Editor. It’s also a lot easier to get to the source code editor, as there is now a button in the XML Editor.

When you are using the XML Editor, click the “Send this File to Text Editor” button, which is now in the XML Editor toolbar.

The code view opens in a separate tab:

This image is kind of small, but you can see that the code editor includes line numbers and color-coded tags. When you make a change and save it in the code view, the change is automatically reflected in the XML Editor (WYSIWYG) view. Flare finally includes a code editor that makes me want to use it instead of an external editor!

In addition, you’ll notice new formatting indicators in the XML Editor. These help you see where the invisible tags are in your source code. For example, the following image shows the Flare 5 XML E

There are three things in the screen shot that are new in Flare 5: First, spans are now identified in the XML editor. Look at the word “originally”; notice the blue brackets around it. These indicate that there is a span applied to that text.  This makes identifying spans easier. They (obviously) don’t affect your output, but when working in the XML editor, you can easily see where the spans begin and end.

Second, notice the condition tag that is applied to the “[5]” reference. Now when you apply conditions in-line as spans, not only does the background change, but now there is a box showing which conditions have been applied (just like you see next to content in the Content Explorer, or in other areas in Flare). This is a small, but very nice enhancement.

Third, Flare now shows you empty tags so you can remove them from your code. In the case of the image above, there is an empty <p> tag set. I can delete it from the XML editor, or I can open the code view to delete it there.

DITA Support

This is the headline feature in Flare 5, and for good reason. You can now import DITA projects into Flare, edit them in Flare, and then generate any of Flare’s output types. This is a groundbreaking achievement.

As with other Flare import types, you can continue to author in a native DITA application and use Flare as a publishing engine, or you can take existing DITA content, import it into Flare, and then use Flare as your authoring tool. In either case, you can then publish your DITA files directly to PDF, WebHelp, Word, FrameMaker, etc.

Flare 5 also has a DITA target output type. This means that you can export your Flare project as a DITA project that you could then transport to any tool that supports DITA.

This is cool for so many reasons, especially when you consider the implications of project collaboration. DITA is quickly becoming a standard format for technical documentation. Being able to export your project to DITA means you can send your project to anybody who uses DITA, with whatever tool they use, and they can open and use your project. If your localization team supports DITA, you can send them a DITA export of your project for translation. If you need to send your project to a client for them to modify at a later date, you don’t have to worry about tool compatibility, because as long as they can work with DITA, you can send them files they can use. And if for some incomprehensible reason you want to use a different authoring tool, you can export your project to DITA, and import it into some other tool.

This is the end of proprietary file types! Your content is YOURS to do with what YOU WANT. You don’t need to rely on somebody creating a transform that can convert MadCap’s content into an importable format for another tool, because you can create a DITA target.

This version of Flare does not yet support native DITA authoring. While you can get DITA in and get DITA out, the project in the middle is a Flare-based project with the Flare-based XHML source files. However, a future version of Flare is supposed to provide native DITA  authoring.

If you are using DITA, or if you are considering how DITA can be used in your organization, you ought to check out Flare V5, because the direction they are going with DITA support is literally awesome.

PDF Target Enhancements

Flare 4.2 addressed some PDF enhancement requests, in that it allowed you to modify the image compression settings for creating PDF files. That was a nice feature, since you finally got some control over how images would be compressed and how that would affect your overall file size. However, you still needed the paid version of Acrobat in order to set the metadata (like author, etc.). No more. Look at what is available to you now:

Now I can truly build and release without any post-processing. I run a script nightly that builds all my documentation and places it in a location where the software build script can pick it up. Now that script builds releasable documentation. That is awesome, and this is a small feature, but one that adds a great deal of value.

Relationship Tables

DITA supports relationship tables, so Flare 5 now supports relationship tables. The Center for Information-Development management has a good article that describes DITA Relationship tables. To summarize, a relationship table is a centralized location where you can link related concepts, related tasks, and reference topics.

In Flare 5 you can insert a relationship proxy into your master page, and then every topic that is linked in the relationship table will show the relationship in the topic, grouped by concepts, tasks, and references (if a relationship exists for that topic).

When you need to update these references, you do them all in one place: the reference table. There is no need to go into individual topics and tag them with a concept; no need to add “related topics” manually. You can have these appear automatically in topics with the relationships proxy.

I have only used this superficially until now, but I plan to use this feature extensively in my next project, so I’ll keep you updated on how it goes.

Other Enhancements

There are several other enhancements I’ve discovered in Flare 5 which include:

• Topic Tool bars
• Thumbnail Image Support
• Text Redaction Support
• Improved Performance
• Conditions in Project Organizer
• Backup Differences
• New Toolbar buttons

Topic Tool bars

You can now include a toolbar anywhere in a topic, which is pretty cool. Here is a skin I created for a project I was working on. I made tabs for the tool bar, and then I moved topic-specific stuff into the topic toolbar, which I floated right. So there you can search the topic, remove highlighting, or mark the topic as a favorite. Since these are topic-level tasks, it makes sense to add them to a toolbar that is in the topic itself.

This feature greatly increases the flexibility options for creating custom skins.

Thumbnail Image Support

Flare now supports image thumbnails. You can create a thumbnail class and apply it to your images. Flare will generate a smaller version of the image, and when users hover over the image (or click on the image, you decide), a larger version of the image can be displayed.

The help system gives detailed information on how to set up and use this feature in your projects.

Text Redaction Support

If you produce sensitive documents, Flare now supports text redaction. With text redaction, you can generate two versions, say of a PDF file. One can contain the full text, and one can contain the redacted text.

You might wonder why you would want redaction when you could conditionally exclude content. In some cases (particularly in government applications) it may be preferable to produce a document with redacted text, rather than just not containing the text. Additionally, when you redact text (instead of excluding it conditionally), the page counts stay the same in both versions of the document.

Improved Performance

Flare 5 sports improved performance, especially surrounding WebHelp target generation. I don’t have any hard numbers here, but it just feels faster. It also seems to have improved stability, based on my experience using it. I can’t remember a time during my beta testing of Flare 5 that the application crashed on me. That is a far cry from the days when I was using Flare 3, which (for me) seemed much less stable. (There was a time, using Flare 3 that Flare was crashing every day at least once, so for me, the improvements in Flare 4 and Flare 5 are fantastic.)

Conditions in the Project Organizer

You can now use conditions in the Project organizer. This allows to you exclude content from the Project Organizer, based on conditions settings in the target. So, if you have separate deliverables in the same project and you want to separate the header and alias files based on the target, you can–and you won’t get any errors when you generate the build!

Again, this is a minor enhancement, but it is one that will make things a lot easier for many people.

Backup Differences

If you use the backup options in Flare, you can now view a diff of the current version from the one that is backed up, which you can view in code view, or in WYSIWYG view.

New Toolbar buttons

There are two new buttons available on the toolbar or the topic toolbar. There is now a Previous button and a Next button. If the topic is part of a browse sequence, then the previous and next buttons show the previous/next topics in the browse sequence. If the topic is not part of a browse sequence, then the buttons show the previous/next topics in the TOC. (This won’t work properly if the topic is added to the TOC in multiple places, or if a topic is not in the TOC.)

Conclusion

Flare 5 is a great enhancement to the Flare product line, and includes more features than the ones I’ve listed. If you are in the market for a help authoring tool or if you are using DITA, check out Flare V5; it will knock your socks off. If you already own Flare, upgrade when it is available. Kudos to MadCap for coming up with a great product with enhancements that really improve the technical author’s workflow, making producing great content faster and easier than ever before.