Project Notes: 4/15/09

Webinar Do-Over

Suncoast STC hosted a webinar last night. Looks like we’re hosting it again next week, too, because it didn’t exactly happen. Tom Johnson was going to speak about WordPress, and take questions, but we spent 40 minutes trying to figure out the GoToWebinar interface. That would be because it was pretty much the first time I was looking at it.

Tom was very, very nice about that. He never said anything remotely like “Why the heck didn’t you find out how this thing worked?” He did say, “Webinar software is not really that easy to use.” So nice of him–seriously. It’s not easy to be that kind when you’re on the spot the way he was.

So: we’re refunding, rescheduling, and practicing ahead of time. And it’s going to be fabulous.

Blogging

There’s been more activity here, lately. I’m doing the 31 days to a Build a Better Blog challenge (sort of) which isn’t turning out to be that hard. Some of these things (linking, promoting) I was already familiar with. It’s the email reminder to post regularly that has been helpful. I read the tips and teachings, too, though. Sometimes I have to “hear” someone say it to remember what needs to be done.

I think most days I should have something to write about, between work and STC. Writing about it will only make the lessons more coherent, and stickier. And, out there in other offices, tech comm folk are having similar experiences—wrestling with HATS, Tweeting, explaining themselves to programmers, loving and hating words for purely aesthetic reasons. I may as well be the one to put myself out there.

STC Summit: Excitement Mounts

Sorry. Couldn’t help it.

Anyway, I’m going to the Summit. I reserved my room. I have a business case in to the chapter to cover various fees. But no matter what, I’m going. I have my Twitter badge ordered, for Pete’s sake. I can’t wait to sit back and soak in the Tech Comm wisdom. I’ll also be networking for presenters and for ideas on boosting chapter participation. I’ve got a pre-conference to-do list augmented by Charlene Kingston’s recommendations. I’ll be armed with business cards, handouts, and a strange affinity for Hyatt hotels. Look out.

Condition Guidelines for Flare Projects: Part 2

In Part 1 of this post, I listed our department’s new guidelines on applying conditions in MadCap Flare. Conditions are one way you can include or exclude content when you are single-sourcing in Flare. After The Project, our crash course in project linking and conditioning, our manager drew up some guidelines that we’re adopting for the next few months and trying out on a test project. I think they’re pretty close to finished, though. This is Part 2 of those guidelines.

Defining Targets

I define a target for every deliverable: User Manual, WebHelp, .chm help, System Admin Manual. If you have a separate target for each deliverable, you can set the conditions (and other settings) and leave them. Here’s what to expect:

• When a topic or paragraph has two conditions applied to it and the target is defined to include one of the conditions and exclude the other condition, the conditioned material will be included in the final output.
• When a topic or paragraph has two conditions applied to it and the target is defined to exclude one of the conditions and nothing is defined for the second condition, the conditioned material will be excluded in the final output.
• When a topic or paragraph has two conditions applied to it and the target is defined to include one of the conditions and nothing is defined for the second condition, the conditioned material will be included in the final output.
• When a set of topics or paragraphs has two conditions—one applied to some files and the other applied to some other files—and the target is defined to include one of the conditions and nothing is defined for the second condition, the material with the second condition will be excluded.

This last one was discovered while testing in preparation for these guidelines. I wish we had known this when we linked all the files up for The Project. This lets each writer only pull what they know they need from a slave project, with minimal interference with the other writers sharing the project.

Another tip: If you don’t choose define any condition settings in your target, and you’re building a help system, all files will be included, even if they aren’t on the TOC. Users will be able to find them in search.

Managing Condition Sets

In a nutshell, condition sets became as controlled as our CSS. Which makes sense to me.

• Do not rename the department condition set file or add any conditions to it.
• A new condition set file should only be added to support different versioning information
• Any new condition set file needs to be approved in advance by the Tech Comm Mgr or Team Lead.
• In most cases, Not For Users conditions should only be used to add information to the base files. That is, use conditions to add information on an upcoming release while maintaining the integrity of the baseline files.
• A new condition set file should follow the set naming convention. Within the condition set file, conditions should be added with the appropriate naming convention.

Version Conditions vs. Archiving

We determined that we don’t expect to use the version conditions much unless multiple development lines of a product are being maintained. We will archive a copy of our projects at each product release. We’ll use these archived copies to produce any deliverables we’ll need pertaining to that release. The working project will continue to be built upon those base files without conditioning for versions.

Tell Me Again Why I Like Conditions

Even though it took years off my life figuring out the conditions for The Project, I enjoyed it. I liked the challenge of knowing that when we found the right combination of conditions and linked projects, we would be sharing files where previously we had duplicated work. The moral is: conditions can do a lot, but they can’t do everything. And they’ll probably do something that you weren’t expecting, so leave plenty of time to QC.

Condition Guidelines for Flare Projects: Part 1

Applying Conditions

Conditions – how do I love them? Well, let me either count the ways, or count the duplicate, missing, unused, and capricious conditions that have made their way into our shared files. As soon as we began linking up our Flare projects and passing them around, it became apparent that someone was going to have to cut us off.

Some one had a condition for every reviewer: Joe, Mary, Tim. I had one for every status: To Edit, To Be Reviewed, Approved. I fought for that as a separate condition set, since it was convenient for seeing at a glance which files needed work. I was finally convinced to use a separate TOC for topics-in-progress. Like, duh.

And let’s not forget the conditions that were duplicated across multiple condition sets—some files had Print Only from applied from the Default set, others from the custom project set. I’m not looking forward to rooting those out.

After several combined hours of discussion, the some department guidelines were born. This first post covers our guidelines for applying conditions. In the second post, I’ll give our guidelines for defining target conditions and managing condition sets. These guidelines were written by our manager. The peanut gallery is all me. And if you’d like another good overview on Flare conditions, check out Paul Pehrson’s post about them. They seem to frazzle him less than they do me, though I don’t know if anyone can love conditions like I love conditions. That said; here are our guidelines:

Whenever possible, write around the need to use conditions.

• For example, if your text refers to a “chapter” or another type of text that is appropriate for a user manual, do not condition it out for a Help system. Rewrite the text to be applicable in both.
  This might seem to defeat the purpose of having conditions, but the more conditions you use the more likely that somewhere the conditions are at odds with each other. Each place that you apply a condition is a place that you have to check whether the outcome is what you expected.

When conditioning an entire topic or group of topics, apply the condition in the Content Explorer pane (not in the TOC). Do not apply conditions in the TOC.

• Talk of this rule started when we realized that applying conditions to the TOC did not remove them from a .chm or WebHelp build. That works to condition content out of a Word or PDF output, but in a help file, the topics will still turn up in a search.
• Additionally, some folks were applying the conditions to the files in the Content Explorer, as they should, but then also applying the same conditions to the TOC, for good measure. This was an unnecessary step, and also misleading for someone coming into your project.
• Actually, I would rather we took a stand on only having a single TOC, in which case we might have need for using conditions on the TOC. But since we are going with the rule for a few months, I will give linking TOCs another try.

Avoid applying conditions within a topic or to sections of a paragraph.

• If applying a condition to a complete paragraph within a topic (preferred use), apply the condition using the paragraph indicators on the left side of the screen. Applying and removing conditions in this way will ensure the underlying code is managed correctly. Two main reasons for this one. First, sometimes you have to go into the code to completely remove a condition. Better not to condition at the sentence level if you can avoid it. Second, if you are linking projects, importing a file only executes your topic-level conditions. For example, if you import a topics from a slave project based on whether they have the X condition applied, great. All the files with the X condition are applied. If you have the Y condition applied to all the Y product names within those topics, you can’t filter those out until you build a target. Each target can only use one combination of conditions. So if you are combining X and Y files into one target, they must have the same condition requirements.

The “NOT for USERS” condition is only to be used at the topic or folder level. Do not use it at the paragraph level.

• Inevitably, when trying to condition something as not for clients at the sentence level has come back to bite us.
  When a project has almost two thousand topics and a lot of conditions, some other condition is going to bring that content to the surface.

Okay, so once you have the perfect conditions applied with finesse and restraint, what next? Tomorrow I’ll post about defining how your targets use conditions, and about how to manage multiple condition sets in Part 2 of this post.

A Word Template for Release Notes

I get so many search engine hits for this phrase, or some variation of it, that it occurred to me I should write the post, already.

Yes, our department uses a Word template for release notes. Here’s why I like it:

• Our template provides pre-formatted tables with repeating header rows for listing the release notes. We print the notes from our release note management application, then cut and paste the records into the template tables. (Each note corresponds to a task documenting a change in the software.) Bottom line; set up your template to accept pasted release note records without hassle. Test it, and if it doesn’t cut and paste easily, be nice to your co-writers and fix it.
• The template contains boilerplate text about the intended use of release notes and other disclaimers that our company requires for every set of published release notes. For information that must be customized per set of release notes, such as product version, you can use fields.
• The first heading of the template contains fields for entering the product, version, and publishing date. We enter that information and then select the Print Preview option, which updates date and product fields in the footers of the document.
• In our template, the first couple of pages of boilerplate text are in Portrait page layout. After those, the pages with the list of notes are in Landscape layout. The enhancments are listed in the first table and the defects are listed in the second table. There is a section break after the boilerplate text and another one between the enhancements and the corrections.

We recently updated this template to use Arial font in all the styles, which I can’t stand. I’m just anti-Arial, though. Other than that, our release note template makes publishing the finished notes the most painless part of the process.