Archive for MadCap

DITA, Blaze, and more

Posted in Blaze, DITA, MadCap, MadCap Blaze, MadCap software, technical writing with tags , , , on September 25, 2008 by Mike

We’ve been deluged with requests for more information about what we’re doing with DITA since the email that went out this week.

So here’s what I can say right now:


You have to wait until Oct 29, like everyone else.

I’m sorry.

But it’s going to be cool, so take a deep breath. It’s all good. Really. Have a cookie and be patient.

And as you eat that cookie, here’s something cool about Blaze.

Blaze tip but first a story

One of the features I really like in Blaze requires a short story to contextualize why I like this feature so much.

When I was docs manager at my previous job, I had 13 writers scattered all over the world. When I started, we had a Frame template but it wasn’t branded and hadn’t been updated in a long time. So we created a new one. If you’ve ever been part of rolling out a new template, you know this is an iterative process, as you start applying the template to new manuals. You discover situations you didn’t think about. This was especially true for us, as we had hundreds of manuals.

So we tweaked for about a year, as the template was applied to more and more kinds of manuals and situations.

We uploaded the Frame template to the Sharepoint site and sent email to the writers that the template was changed and they should update their current projects. My staff was first rate but they would forget and didn’t update. We wouldn’t find out the template was out of date until the Production Review, which is exactly the wrong time to catch it. At that point, we were trying to get the Gold build of the docs and taking time to apply the updated template was a serious impact.

It also made me cranky, because I was trying to build credibility for the group, make us look competent and part of the team. It was a strange place that, over drinks one day, I might tell you about.

Blaze tip

Blaze – and Flare 4 – has a feature called Global Project Linking.

1. Add a Blaze Project Import to your Blaze project and get this screen:

Blaze Import Project

Blaze Import Project

2. In the Source Project field, browse and open another Blaze project.

3. Select the files types you want to include or exclude from the lists.

4. Select the “Auto-reimport before ‘Generate output'” check box.

OK, so why is this cool?

What you can do is create a template project with all the page layouts, snippets, logos, style sheets, everything that belongs in all projects from your company. Save that project to a network location that everyone can get to.

Now all writers link to that project using Global Project Linking. All the specified content from the Global project is now available in each linked project.

If that template project changes, the “Auto-reimport before ‘Generate output'” check box makes sure those changes are brought into this project when any target in this project is built.

That current template issue I faced in my previous company? A non-issue now. Everyone is now linked to the template and they are always updated with the latest changes.

No looking like a dork because you sent an outdated project to the build.



A quiet Saturday morning

Posted in Blaze, Flare, MadCap, MadCap software, Personal with tags , , , , on July 26, 2008 by Mike

Husband is still snoring, I have dogs sleeping on my office floor, and it’s quiet on the street. This is why I’m a morning person. About 6:30, the sun was streaming thru the wall of windows on the eastern side of the house. I wanted to twirl slowly in the golden light.

It’s a dogs’ life

It’s been pretty animal crazy in my life lately. Our 14 month old Aussie came down with very bad kennel cough and was really sick for about 10 days. Gus (and our other 2) was immunized against the bad common strains, but the vet explained this is like a cold for humans – the virus keeps mutating. As it turns out, the virus that causes kennel cough is related to the bug that causes viral bronchitis in humans.

Gus spent 10 days laying around coughing. He couldn’t walk across the room without a 15 minute coughing fit that wore him out. He had no sparkle because he was just too sick. Finally, Thursday morning of this week, he started recovering. Now he wants to play and run and only coughs a little. A totally healthy dog is not too far away.

In the mean time, the Cattle Dog, Sara, is getting very old and crippled by her arthritis. I know this is her last summer but I’m hoping to give her a last summer (her favorite time of year because she can swim in the pool). Husband and I met with the vet who said “Soon and not long, but not yet” and gave us pain pills to help her. These seem to working OK with her for now. And she continues to wag her tail when I come home.

And, because this is how it goes, the very old Border Collie mix, Lady, is less and less tethered to this life. She’s blind and deaf and losing weight. I expect when we put Sara down this fall, Lady will go to sleep and not wake up soon after. They’ve been together since they were about 8 months old. I’ve never thought one of them would survive much beyond the other.

Surprisingly, the old dogs did not pick up this round of kennel cough. Which is good because at their advanced ages, I think this one would have killed them. Gus is young and resilient; Sara and Lady simply are not anymore.

I’m not excited about this part of having dogs. I like the young part of their lives. I’m not delighted with the old and crippled part of this at all. But this fall, decisions will have to be made, regardless of how much I like these guys sleeping on the floor in my office.

In other news

The week was crazy busy at work—the Importing FrameMaker files into Flare  webinar is insanely popular. And I usually have people with many questions afterwards about their specific situation.

After each webinar, I spend probably 3 hours helping people with their stuff. I love it, because it all teaches me more about what you all are doing with our products and what challenges you face. This will only help me get you better products in the end. I know better what you need and can advocate for it.

We also have MadCamp this coming week, so we were busy getting ready for that, making sure all we need is in place to have that be a success. And I think it is! Whew.

All in all, a week that left my brain vibrating in my head every evening.

This weekend’s plan

So this weekend, I grade student papers because I’m 2 weeks behind and they’re starting to murmur. We have a party at my best (female) friend’s house, a friend is in town on business starting Sunday and I’ll try to have lunch with him tomorrow, I need to do laundry and generally pick up, I have 2 – count them 2! – new fabulous crochet pattern books to start working from (both sweaters and shrugs and the like – yum!), and a husband to talk to. And dogs to pet.

And if I have time, I want to practice my knitting. I took a lesson last weekend and it was hard but fun. I’m such an experienced crocheter that I’ve forgotten how it feels to be new at these handicrafts. Knitting humbled me. I want to get OK at it. I may never prefer it, but I think I should know how to do it competently.

Why? Because I enjoy having a picture in my head that translates to a thing through my hands. I find it calming to work my hands to make something. I like working on a craft (art) that’s been practiced for perhaps a thousand years. I like feeling as though I’m dipping into a sea of tradition that’s been practiced by far more talent than I’ll ever have.


And as a last note, today is Michael Stern’s birthday. If you never got to know him, you missed out on knowing an amazing and wonderful man. Michael was my best male friend who died suddenly one night about 3 years ago. Losing a best friend is every bit as bad as it sounds. As I spoke in his eulogy, some things you never get over, you just adjust to. Eventually, I suppose.

Happy Birthday Michael.

Frame to Blaze updated

Posted in Blaze, MadCap, MadCap software, Personal with tags , , , , on June 18, 2008 by Mike

I’m in my town today, 100 miles north-north-east of San Diego and it’s hot. 104˚ in the shade, baby. I like hot but this is a lot to ask.

Baby, it’s hot outside

Normally, we wander into the heat, every day a little warmer through spring until mid July when it’s 104˚. Not this year. This year it was cool and cool and BAM – hot. Yikes.

And the rainy season is over. Unlike a lot of the world, in So Cal, we have a 4 month rainy season and then we have sunshine for 8 months. It sounds good and usually is but after about 6 months, you long for something other than “Sunny”. And then the fires start and you wish you had “Sunny” back.

We do have 4 seasons in So Cal, though: Fire, Flood, Green, and Brown. We’re transitioning to Brown now. Brown can last up to 6 months, but no one wants that. Sept to December are our worst Fire months so we prefer to go right to Flood in October if we can.

I don’t want to complain too much about the heat now though- we could be under 10 feet of water, like the midwest. I’m sure they would like to see a month or 2 of no rain.

Frame to Blaze Best Practices updated

OK – I’ve been working with Blaze, as I hope you have too, and I’ve updated the Best Practices document. So, please, download the document and work with Blaze. it’s here: frametoblazebestpracticesdraft41

We refreshed the beta early this week and I like it. We just (hopefully) fixed a very nasty bug this week and after some testing, you should see it in a week or 2. Stay tuned for that.

Time for the pool soon

I’ve been giving our young dog swimming lessons the last few weeks. Of course, dogs know how to swim but they drowned in pools because they don’t know how to get out. So if you have a dog and a pool, you have to work with them so they know how to get out.

What that means is I get in the pool. Gus gets very happy because we’re going to play with the ball. I throw the ball in the pool. He walks the hot tub wall (carefully, because it’s narrow and he’s 75 lbs) and looks at the ball in the pool.

He looks at me.

He thinks it thru.

He leaps into the water, goes under, comes up, and swims for the ball. He gets the ball.

Depending on where in the pool we are, he either heads for the stairs or for the seat at the other end of the pool. If the seat, he sits, looks at me and then goes for the stairs. The entire time, I’m telling him he’s a good dog.

Rinse and repeat.

The old Cattle Dog, Sara, has loved her pool since she was taught pool safety some 14 years ago. But now, it’s really hard for her to get her old stiff bones in and out of the pool. She falls most of the time, trying to get out.

Now she walks along the side of the pool, huffing and barking at Gus. It really looks like she’s coaching him.

I think Gus is having fun in the pool with me but I’m not sure. In the end, it doesn’t matters if he likes it so long as he’s safe around the pool. But it would be more fun for the whole pack if he liked it. His toes are webbed to the last knuckle, so he could be a strong swimmer. If that’s what he’s into.

After all, it’s the Brown season!

STC in Philly

Posted in Analyzer, Blaze, Flare, MadCap, Personal, Tech Comm, technical writing with tags , , , on June 2, 2008 by Mike

Well, the first full day of the STC International conference is over and I’m back in my hotel room. I’ve ordered room service and a glass of wine. My feet and legs hurt and my brain is going to explode.

It was a very fun day.

The MadCap booth is amazing – 20 feet by 20 feet and visible from anywhere in the large vendor area. Mike took pictures and we’ll have them posted soon. But it’s large and looks great.

We’re doing demos all day on various products and they’re really well attended. The buzz is strong.

As usual when I go to a conference, I have seen lots of people I’ve not seen for a while, so much of my day is spent smiling and hugging people. I really like that part of my job.

Room service is about to appear and I have an entire day of email to catch up on. More later in the week. I need to eat and drink a glass of wine. The day starts at 8:30 tomorrow morning.

Man, the STC webinar was fun!

Posted in MadCap, Tech Comm with tags , , on May 19, 2008 by Mike

The webinar we did for STC last week sold out in about 3 hours, which stunned me. I had no idea the topic was that exciting to everyone. I guess to me topic-based content development is like air, but I see now that people are really looking for advice on how to do it and why.

Oddly nervous

For the first time in a long time, I was nervous. This was 250 sites and it’s been a while since I’ve spoken for that many. I was also worried that I wouldn’t convey valuable information and people would think this was a waste of their time. It was sort of like doing standup comedy, in that I also couldn’t see the audience. Unlike standup, tho, I couldn’t hear anyone. So I had no idea if my jokes were going anywhere.

(Ask me about some of the worst stand up performances I’ve ever had sometime. Silence is not always golden)

But I think it went well overall. I talked much too fast for the first 10 minutes, as I do when I’m nervous. But I settled down and I think it was OK.

June is my very favorite month

If you wanted to attend the STC webinar and couldn’t get in, keep watching my blog. We are doing something in June that may help you.

Speaking of June, 2 great things are happening.

The first is the STC International Conference in Philadelphia.

Brief divergence

The last time I was I in Philly was 1980. My first husband and I were living in Naples, Italy and had come back to the States for a family emergency. Because he was active duty US Army, we flew thru Philly on standby military flights both way.

On the way back to Naples, they had room for my husband – because he was active duty, he had priority – but not for me and Matthew. The next flight was a few days later so the military put us in a hotel for two long, boring days. I was traveling with a 2 year old in a city I knew nothing about and I was 19 and very shy.

(No one ever believes that I was painfully shy when I was young, but it’s true. I could barely speak to strangers.)

Back to the main topic

I’m guessing this time will be utterly different, if for no other reason than I am several husbands later. Oh, and I’m a little more outgoing now. That’s also changed.

We have an amazing booth for the show. Come by and see it. We’re also giving away a lot of stuff, so make sure you’re in that loop.

The other cool thing that’s happening in June is my birthday. I love my birthday. It’s the beginning of the universe. I’m thinking seriously about going to visit my son for my birthday this year so you may get some more children pictures posted over the 4th of July weekend.

I miss Matthew and want to see him. My eyes are happy when I see him.

So, if you’re at the STC International conference, swing by our booth and wish me an early birthday.

Reading-to-learn and cognitive loads

Posted in MadCap, Tech Comm, technical writing with tags , on May 14, 2008 by Mike

While I was in Vancouver, you may remember, I read a great article about cohesion and coherence from the ISTC magazine. I mentioned that there was an STC Journal article about a year ago that related but I couldn’t remember how.

I found the article.

It’s The Effect of Heading Frequency on Comprehension of Print Versus Online Information by Alexandra L. Bartell, Laura D. Schultz, and Jan H. Spyridakis. Technical Communication, Vol 52, no. 4, November 2006. pages 416 to 426.

So, what’s the article say, Sharon?

Oh, many interesting things. Get another cup of coffee. And cookies. Everyone needs some cookies.

Except the woman who stopped in front of me this morning on the freeway and then slowly rolled 30 feet backwards into me, despite blowing my horn, yelling out the window, waving my arms, and backing up my car as much as possible. She doesn’t get any cookies.

She was going less than a mile an hour so there was no damage to my car or hers. Which is a good thing, considering how mad I was. But she still doesn’t get any cookies. (My car won’t go, she said, when asked why she hit me. Well, I said, it seems to have no problems going backwards. Maybe you should put it in Park until I’m gone.)

Back to the article

OK – now that you have coffee and cookies, let’s settle in.

On the first page, they talk about:

One area of empirical research with considerable information concerning print documents is that of “signaling.” Text signals consist of preview statements, overview sentences, headings, and other cues about the content and structure of a text. Empirical studies tell us that when readers who are “reading-to-learn” encounter signals in print text, they are better able to comprehend new or difficult information. These signals help readers create mental roadmaps or schemata of a text’s structure and content that in turn help them absorb new information. As readers take in new information, they instantiate existing schemata, adapt them as needed to fit the new information, and at times, even reject the new information. [p 416]

These seem to be the cohesive devices mentioned in Ward’s article. And they seem to be saying that cohesive devices create the coherence in the users’ minds. I’m good so far. We’re consistent with Ward’s article.

What are headings good for anyway?

They go on to wonder how the frequency of headings in print or online might impact comprehension (comprehension being cohesion, as it is in the mind of the reader and is testable). Headings are important as signals because they help the readers understand the structure of the text and assign meanings (create schemas). “The importance of text signals is evident when one realizes how much readers use cues in a text to help them discern a text’s meaning.” [p. 417]

However, difficulty of the text or reader motivation seems to matter in using signals for coherence.

[…] if readers lack domain knowledge or find a text difficult to comprehend, signals that provide text coherence may help them better understand the material. In contrast, text that readers perceive to be easy does not benefit from signals—in such cases, readers have little need for the extra help that signals could provide. Similarly, if readers find the information enjoyable to read, they may be less likely to need headings or other signals to help them understand the content. [p. 417 with references removed]

However, headings may be problematic in online text:

Because readers tend to scan online text, many Web usability specialists have called for the use of more headings in online text. Although such advice may be valuable for readers who are “reading-to-do” and who are thereby searching online texts for specific information, it may be less appropriate for readers who are “reading-to-learn.” [p. 417 with references removed]

Reading-to-learn vs reading-to-do

Reading-to-learn are people who are reading for learning the material for some reason. For example, they may be interested in consumer goods and how to reduce their consumption, as my son and his family are interested in. So my son sends me lots of reading-to-learn information links to help me know more. One of the goals to reading-to-learn is recall.

Reading-to-do is reading information with the intent to act on that information. Product documentation is a good example of reading-to-do material. You expect that your reader will read some of the material and then turn to the product and do something. Reading-to-do is short term. Recall is not usually a goal.

Cognitive loads can be so heavy

They also give good definitions of cognitive load, which you should be familiar with if you’re not. It’s an important concept for us, because our users don’t come to our materials with nothing else going on.

[…] three types of cognitive load that could help explain comprehension differences in print versus online environments:

  • Intrinsic cognitive load, which is inherent in the material itself
  • Extraneous cognitive load, which is imposed on the user by the format and way that the material is presented
  • Germane cognitive load, which involves the learner’s attempts to process and understand the information [page 418]

They suggest that online docs users may have an increased overall cognitive load because of the nature of online docs. Navigation, hyperlinks, and other common online devices may add to the cognitive load while the reader is trying to understand the material. So getting to that germane cognitive load part of the brain could be a little harder for online readers than book readers.

The point to their research

They found that reading-to-learn readers reading online material did better overall with headings that appeared at a medium frequency (1 heading for about every 200 words).

[…] readers of print-based text are able to comprehend more of the text than readers of online text regardless of heading frequency. And this may be particularly true of our reader population, readers with little prior knowledge of the topic or personal motivation for reading the information—even though our readers were extremely experienced in Web environments. [p 422]

Another of the interesting findings (and they had several more I won’t get into here)

[…] readers of the print text were much more resilient to heading frequency extremes than the online readers. In comparison to the online readers, readers of the print texts had relatively similar comprehension scores regardless of heading frequency. In contrast, readers of the online texts had higher scores with the medium-frequency heading condition and considerably lower scores with the high-frequency and no-heading conditions. The significant interaction of display medium and heading frequency reveals that the comprehension of online readers is much more susceptible to weak structural cues (such as too many or too few headings) than is the comprehension of print-based readers. [p. 422]

So what does all this mean?

Oh, sure ask me that. I was hoping you could put this together yourself. Fine, I’ll do the heavy lifting. You just sit there and eat that cookie.

What this all means is that the signals you use to create cohesion (headings) must account for the delivery method for coherence to happen.

For example, people who are reading-to-learn online need heading signals about every 200 words. So, if your sentences are less than 25 words each and your paragraphs are less than 5 sentences, you need a heading about every 2 paragraphs if you are delivering the info online to your readers.

If you are delivering the information in a printed form, you have more wiggle room with your heading signals. You could go as far as a heading every 300 words and still get coherence.

Future research directions

In good Graduate School form, I end this article with a call for further research.

But in truth, we really need someone to do this work with reading-to-do material. We have guidelines for teaching people the concepts in our materials now. But what about the people who just need to program the damn remote control again? What signals are best for them so they get coherence? Do they need coherence? Do they even need cohesion?

If you know about any research that speaks to this, let me know. I’m very interested in that.

Seriously, I had no idea

Posted in MadCap, Tech Comm with tags , , on May 7, 2008 by Mike

Well, the word about the Topic-based content development STC seminar went out to people as I got on the plane yesterday. When I got to Vancouver and was able to get to my email (about 7:30), the webinar is full. We sold out in about 6 hours.

Wow. I had no idea this topic would be so popular.

Thanks for the emails

And my email box was full of people who wanted to get in, or the STC web page wasn’t working for them, or they were confused about the date on the STC page, or thought that the Director of STC shouldn’t ALSO work for MadCap (totally different Burtons), and so on.

I pointed all of them to the STC people, as I have no control over the STC website or how signing up works or really anything on that end.

So, I guess I need to finish the last touches on the slides! I like to write a presentation, let it cook for about 3 days and then revisit it for logic and flow.  

Downstairs, here I come!

I need to get myself together and get downstairs. The vendors part of DocTrain today starts at 10:30. And I need to get moving.

I’ll write more later.