Technically Speaking

Not too long ago, I found myself stuck between a rock and a hard place. I work for a large organization (30k+ world wide workforce), and I’m just one tiny fish in a very large lake.

I was asked to provide help content in the form of a getting started guide for a piece of software that was going to be released world-wide.

I started working on the project using my tool of choice, a help authoring tool called MadCap Flare. This is a tool I really like, and have been using for several years. I’m something of an expert on Flare, so it is my first choice for pretty much any authoring project.

I started working within my group, however, and found that Flare wasn’t going to be the right solution for this project because of project constraints outside of my control. We have an in-house translation group that does all our content translation. They have their tools in place and are not interested in obtaining and learning to use a new tool (MadCap’s Lingo tool). There are certain strings in the project (specifically surrounding variables and master pages) that wouldn’t get sent to translation if they didn’t use Lingo. This project is going to go out in 24 languages, so simplifying the process is essential.

Read the rest of this entry »

As a technical writer, I develop content for the applications I’m supporting. Often that includes designing content, images, and multi-media to provide the best user experience possible. As content developers, however, we have a responsibility (both legal and moral) to ensure that the content we are using is being used properly and legally.

We live in a world with lots of avenues to get content for our projects. Several websites specialize in searching for media that you can download and use in your product. Just because you can find it, however, does not mean you can use it. There are legal requirements that you need to be aware of when you are using content created by somebody else.

For example, I can’t just do a Google image search and find any image and put it directly into my project. The person who created that image has copyright protection on that content. You can not use it unless you get a license to use it from the copyright holder.

When you are working on a project for personal use, you probably don’t have to be too worried about these restrictions. However, when you are doing work that will be used in any kind of professional setting or commercial setting, you have to be very careful how you use others’ intellectual property.

Take, for example, the case of NBC currently in the news. NBC is being sued for using somebody else’s intellectual property, without properly licensing it. A very similar thing happened at a company where I used to work. The company had been purchased by a larger entity, and was going through a re-branding. The new branding used a font that the company hadn’t licensed properly. When I read the license agreement and realized we were infringing on somebody’s IP rights, I escalated to the management, who had to pay tens of thousands of dollars to use the fonts the way they were planning to. However, paying those tens of thousands of dollars up front saved them potentially hundreds of thousands of dollars in the lawsuit that might come from using the fonts illegally.

Since the work you create represents the company you work for (or your own company, if you are an contractor), you really need to pay attention to intellectual property issues to protect your company from being held liable for infringement.

Here are some tips for using intellectual property properly:

• When you use somebody’s material, be sure you get written permission to use it, including exactly how it will be used. If you are going to use it for commercial purposes, be sure that it is properly stated.
• Don’t just assume that people put the content on the Internet so it can be used.
• If you purchase stock photography, make sure you abide by the terms of the license agreement. Generally, you don’t purchase unlimited rights; normally your license restricts how the property can be used (if it can be downloaded, for example; or if it can be used on a T-shirt or mug).
• If you create something from scratch while at work, that work belongs to your employer. You can use that in your work product in any way you want. If you make a derivative work, you have to be sure you are licensed to do so.
• “Fair use” is a defense in court; it is not a legal protection, per se. Be very careful about saying “I can use this, because it is ‘fair use.’” You don’t want to get sued to prove that it is, in fact, fair use. When in doubt, don’t do it.
• Track your IP use. Many licenses to use IP include time restrictions; after a certain date you have to re-pay to continue to use the image. Be sure your organization is in compliance with these rules.
• When you use somebody else’s work, be sure you give proper attribution. In many cases it is required. In other cases, it is just the morally right thing to do.

A special note about Creative Commons License

There are lots of images available out there under a Creative Commons license. There are several forms of this license, but you need to be very careful if you use Creative Commons-licensed material because most Creative Commons licenses require “share-alike.” That means that if you use an image licensed with a Creative Commons license, your entire project must also be licensed under the same license.

That means if you are creating a help system that includes a single Creative Commons Share Alike image, then your entire help system may also be required to be licensed under a Creative Commons Share Alike license.

Watching out for others’ IP rights is good for the community. It means you can also expect your IP rights to be respected. It is the responsible thing for us to do, and as writers, we owe it to ourselves, our employers, and our community to make sure we are in compliance with intellectual property requirements.

_______________

Disclaimer: I am not a lawyer, and this should not be considered legal advice. If you have questions about intellectual property issues, please seek the advice of an IP attorney licensed to practice in your locality.

So it’s been a while since I posted much on Flare. For a while I wasn’t using Flare in my daily work flow; I’ve actually moved all new development on the four product lines I support into my Flare work flow, but we keep needing to go back and do dot releases on an older version of our software. When I thought it was only going to be one dot release, it didn’t seem prudent to move the source into Flare. Now we’re working on the FIFTH dot release. Seems I should have made the switch. Oh well.

Anyway, for about a month now I’ve been back using Flare full-time again, and I’ve really been enjoying some of the features in the 3.x line. I didn’t really delve much into them when 3.0 first came out, so many of the new 3.0 features I’m only starting to use now in 3.1.

In any case, here are my favorites so far:

Running Headers/Footers in Word Output

One of my big complaints about InDesign compared to FrameMaker was that InDesign didn’t have an elegant way of allowing running headers and footers in your printed output. A running header/footer means the header/footer’s content changes to reflect the section of the documentation you are in. So a running header might automatically contain the name of the chapter, and a running footer might contain the text of the most recent H1 or H2 style in the document. This makes the printed document much more accessible, easy to read, and professional.

Flare 3.1 gives you the option to use running headers and footers on your Printed Masterpages. You add a variable set to your Flare project that defines the heading styles you want to grab as the header/footer text, then you insert those variables into your Masterpages.

The result is exactly what I asked for. Then I found out, I didn’t know what I wanted.

See, the running headers/footers work great if you stick to a rigid format (a-ha! the structured authoring debate comes again!) in your document structure (e.g. H1 style for chapter title; H2 style for section heading, etc.). I thought I had done that. When I created my printed output, I realized that I have certain sections in my Flare WebHelp that I have as drop-down heads. The style of the drop-down heading matches my H2 style, so in the printed output, you can’t tell whether the WebHelp uses an H2 or used a drop-down head.

That works great for masking the non-standard structure, but Flare can either use the most recent H2 in the footer, or it can use the most recent drop-down head in the footer. I have to go back to my documents and re-structure them so they are all structured the same in order to use running headers and footers in my printed output.

I don’t blame Flare for that, though. I need to pick a structure and stick with it. It’s not Flare’s fault I’m using two different structure formats in different topics.

I give the running headers/footers in Word feature two thumbs up. Thanks MadCap!

Source Control Integration from within Flare

A new feature in Flare 3.0 was source control integration from within the Flare interface. This is a cool feature that I didn’t know I needed, but one that I like the more I use it.

Flare provides direct integration with Microsoft Visual Source Save and Microsoft Team Foundation Server, and provided third-party integration with other source control systems that use the MS SCC API interface. My documentation is stored in an SVN repository, so I had to purchase a third-party plugin to get Flare to work with my source control system. (I bought my plugin from PushOK software, a vendor out of Russia. It cost me 600 Russian Rubles, which came out to about 25 dollars. I’ve been using the plugin now for a couple of months, and it works fine for me.)

I have only a few complaints here: I wish Flare supported the most common formats natively, so I didn’t have to purchase the plugin separately. And I don’t love how for some actions (like moving a folder of topics to a different location in the tree) it seems that either Flare or the plugin checks in each change as a separate revision in the source control. (I suspect this is the plugin’s doing.) Also, I purchased the plugin for one computer I use for editing the project (my main computer) but I didn’t purchase it for my backup computer. When I edit the project using my backup computer, I have problems because the SVN connection settings are stored in my flare project file, so the project files on my two computers can’t match. I hate having to purchase an extra plugin just for the occasional use of the backup computer, so I’ll probably just ignore the inconsistent settings in my project files.

Basic Style Editor

One of Flare’s strengths is the CSS editor included in Flare. In the 3.x line, they’ve stepped things up a notch by including a basic style editor and an advanced style editor. (The advanced style editor is basically the same editor we’ve seen in previous versions of Flare. The basic style editor is a new concept in 3.x.)

The advanced style editor shows all the inherited and local styles and classes in the style sheet. It also shows all the properties available for the styles and classes and lets you change them. You have quite a bit of control over how much information is shown on the screen; You can limit the styles by group, and you can limit the properties list by grouping by type, showing only set properties, or even a smart list of “relevant” properties–properties Flare thinks you might want to change for that style.

Two areas for possible improvement are: (1) Flare still has a habit of modifying my CSS just because I opened it. Example: for some reason it doesn’t like the asterisk symbol in complex selectors (e.g. ul * ol), and any time I open my stylesheet in Flare, it replaces all my asterisks with a “\00002A” which I guess is code for asterisk or something. (2) There is a toggle button to switch between the advanced view and the simplified view. However, the toggle button text shows you the view you will see if you click that button. So, in the screen shot included here, you’ll see that the toggle button says “Simplified View” even though you are seeing the Advanced View. It’s not a big deal, but it makes for a slightly confusing interface. Not to mention that the Flare help system has to explain every time how to check to see if you are really viewing the advanced view or the simplified view. Simply putting the word “Show” in front of the text would really have made this easier.

Conclusion

I still love Flare. There is a learning curve to get up and running with it, but it is a very powerful tool that in my opinion just keeps getting better and better.

——-

PS: I suppose I ought to post a bit of news (and a sort-of disclaimer). Due to my activity in the Flare user forums, last month I was invited by Flare Support to be a MadCap MVP, and I accepted. I use the pseudonym “DocGuy” in the forums. This doesn’t make me a MadCap lackey; some MVPs are known for speaking their minds in opposition of perceived problems at MadCap. However, I am a volunteer forum moderator for the MadCap Forums, and I am a MadCap aficionado. But I don’t suppose that last bit is very surprising to anybody.

The other day I was walking through a parking lot and I overheard one side of a phone conversation. The person speaking said, “I’m the link between the geniuses and the regular people.”

The comment floored me, because I think that is true about technical writing in general, and about my job at my company in particular. I’m amazed at what our engineers and linguists know and how good they are at developing our software. I work with some seriously smart people. They are fantastic at their job: developing our software. Then I get to come in and become the link between the geniuses and the regular people (i.e. everybody else). I get to make recommendations on improving the user interface to make it more intuitive and easy to use. Then I get to write the documentation that answers all the questions people will have about how to use the software. In a very real sense I’m the link between the geniuses and the regular people.

Have I mentioned that I love my job?

Have I told you lately that I love my job? Twice in the last year I’ve been approached by people who wanted me to investigate another work opportunity, and both times I turned the people down before they could get going. There are so many fantastic things about my job, that I can’t imagine switching into a situation that might not (how could it possibly?) be as good.

The company I work for has a very appealing corporate culture. There is a real sense of family unlike anything I ever expected from a job. I remember when our baby was born last December. I received flowers from the office, and the whole executive team (all but two of whom have offices in California, not Utah, so I don’t hardly know them) sent me individual e-mails of congratulations–the longest of which may have come from the CEO. The office has a dot-com startup feel with people wearing shorts and t-shirts, but the people I work with are exceptionally intelligent and good at their jobs. I’m surrounded by geniuses. I look around the office and think to myself, “I can’t believe that they picked me to work here.”

As for the work itself, it is fun and interesting. There is always plenty to do to keep me occupied. My manager is happy to let me experiment with new tools or other ideas to see how things will work and is supportive and encouraging. I have a lot of autonomy; as long as I get my projects done on time (I haven’t missed a deadline yet, in over a year), nobody is very concerned about where I work from, or what my hours are. I put in a lot of hours near my deadlines, but I’m able to be much more flexible when I’m not at the end of a development cycle.

I feel like they trust me, believe in me, and need me, and are genuinely pleased with my work. There’s no wonder why I love my job. And no wonder why I won’t consider leaving. It may not get any better than this. And a million people would die to love their jobs like I love mine.

So ACME (generic name for the company I work for), this month we celebrate a year working together. Raise your glass as we look forward to many more.