Archive for September, 2008

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:

Nothing.

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.

Cool!

DITA

Posted in Blaze, Flare, MadCap, MadCap software, technical writing with tags , , , , , on September 23, 2008 by Mike

A week

Posted in Personal, Tech Comm, technical writing with tags , , , on September 21, 2008 by Mike

It’s been a very busy week – I seem to say that all the time, don’t I? Well, this was another busy week. But, as is typical of me, a personal tale. This relates to Tech Comm, just be patient.

Miles to go before I sleep

Because I live 100 miles from where I work, I stay in San Diego with my best friend’s family several nights a week. She lives 5 miles from the office and her family is great so this works well. I have a room above the garage with a futon, wedged into a corner, a basket for my dirty clothes, an alarm clock, a shower downstairs. It’s all good.

I come down Monday and go home Wednesday or Thursday nights, depending on how the week is going. This week, I needed to be in Chatsworth at an STC meeting on Thursday night, which is 100 miles from my house but the other direction from San Diego (I’m 100 miles from where I need to be all the time). I wanted to go home Wednesday night to see Current Husband, sleep in my bed, pet my animals, that stuff.

Mystery lights

Wednesday night, I went into the underground parking garage, got in my car, started driving out of the structure. A dash light came on, shaped like an engine block. “Oh, that’s probably not good.” I thought.

I pulled out of the garage and found a parking space on the street in downtown La Jolla. But I was dead in the water. I had no idea what the light meant – was the engine about to explode? Did she need a tune up soon? Did the computer hiccup? The engine seemed to running fine…

And there was no way to find out what it meant. I don’t carry the instruction manual in the car. Not because I’m lazy – I drive a Miata. It’s a 2 seater with a trunk the size of a glove box on the average SUV. I need every bit of space in that trunk to get what I need to San Diego for the week. If I were an inch longer in the body or the legs I  wouldn’t fit in the car with the rag top up. (She’s an adorable car that really goes Zoom Zoom…)

Truth tables

I had 100 miles of freeway in front of me before I was home. I needed to make a decision, based on the information I had, which wasn’t really information at all, in that it would let me make an informed decision. And this decision really mattered, because making the wrong decision potentially left me stranded on a dark isolated freeway in a little sports car. Potentially with a destroyed engine.

So I burst into tears.

And called AAA to arrange a tow truck to go to the dealer. I called the dealer to arrange for an out of hours drop off. I asked about a loaner, which I could get in the morning, they said. I called my best friend, asked for a pick up at the dealer in an hour and told her she had me for another night. Then I called my husband and cried some more.

In the end, everything got dropped off, picked up, and I got back to my friend’s house. In the morning, she took me back to the dealer for the loaner and I flew up the freeway to be home for 4 hours before I drove to Chatsworth for a fine and great evening with the San Fernando Valley STC chapter.

Helpless users are not happy users

The next day, the dealer called and told me it was my gas cap – the seal was gone and wasn’t providing proper back pressure to the fuel system, or perhaps it was the exhaust system. Nevertheless, it was safe to drive but I had no way to know that at the time. It was warranty work and the car would be ready Friday.

At the dealer Friday afternoon, the nice service man told me that in the future, if that light goes on again, I could drive her home. If the light starts flashing, that’s bad and I need to stop driving her right away.

And how would I know that?

Domains and schemas

I’m out of my domain – I’m not a car expert nor do I want to be a car expert. I shouldn’t have to be a car expert to use what is essentially a shrink-wrap technology. 

As a user, I see a light that indicates something is wrong. The light is not normally on and it looks bad because it’s shaped like an engine block. It’s a well designed icon, in that it clearly signals Scary Engine Thing – Pay Attention.

But I have no more information. The light doesn’t distinguish between something is not right and something is wrong. And that distinction is critical to me, the user. I need a little more information than that to know what I’m dealing with. The feeling of helplessness because I didn’t know what was wrong made me cry and that’s not what you want to do to your users.

It’s also not obvious the light could flash – in my experience, in my schema for cars, lights are digital, in that they have 2 states: On and Off. Now I know for my car, at least, there are 3 states, at least for this light. I’m afraid to extend that knowledge to other lights because I don’t know if it’s true for the other lights.

Support your users

Provide enough information to your users so they can make at least the critical decisions. Don’t make them sit on curbs in La Jolla and cry. It’s not nice.

And don’t tell me there’s no room in the interface. Find a way to make it work. These decisions matter to your users. We have an obligation to provide some information to support them in making the right decisions.

See? I told you this related to Tech Comm…

Free is good – you can afford free

Posted in Blaze, Flare, MadCap, Madcap flare, MadCap software, Tech Comm, technical writing with tags , , , , on September 15, 2008 by Mike

We’re doing a series of free webinars in the month of October. We’d love to have you join us.

Importing FrameMaker files to Flare or Blaze
October 3 at 9am
Reserve your Webinar seat at: https://www1.gotomeeting.com/register/667817804

What’s new in Flare 4?
October 9 at 9am
Reserve your Webinar seat at: https://www1.gotomeeting.com/register/562186940

Planning the move to Flare or Blaze
October 15 at 9am
Reserve your Webinar seat at: https://www1.gotomeeting.com/register/385144397

Doing more with less (Tools independant: this is the crazy sold out STC webinar we did in late spring)
October 21 at 9am
Reserve your Webinar seat at: https://www1.gotomeeting.com/register/865719205

I’m doing some and Mike Hamilton is doing some and we’re doing one together. if you are interested in seeing our products or learning about what Topic-based Authoring is, go sign up!

You think you know busy and then…

Posted in Analyzer, Blaze, Flare, MadCap, Madcap flare, MadCap software, Tech Comm with tags , , , , , , on September 11, 2008 by Mike

Then it gets crazy. We were really busy up to release: getting ads put together, finishing the website, scheduling demos, all that stuff.

Then we released.

And it really got busy. I’ve done a demo a day (except for today) all week. Mike has done three 4 hour jump starts and several demos in the last 36 hours alone. Handling questions from people, making sure word gets out, looking for someone to review Blaze (any takers? Pitch it to an editor, sell it, and I’ll provide you a free copy of Blaze.)

It makes a girl want to nap. Long, one might say, for a nap.

So what’s the verdict?

On Flare 4:

I just wanted you to know that I am TOTALLY sold now on Flare. MadCap has made me a convert…There are so many things that I’m impressed with that I can’t take the time to list them!

and:

I just downloaded and started exploring the new features. I have to say, wow. Wow!
I’m very impressed with PageLayouts (awesome, awesome, awesome!), resizing in XML editor, IntelliSense (Wow!), Global project linking (hello CMS!), inserting snippets by drag/drop (about time), and love the Downloads links–key features guide, What’s New guide, etc. (very, very useful content – way to go Tech Writers!).

And other good stuff. I saved some of the Blaze comments but I can’t find them now, so there it is. I’ll post them when I can find them again.

I think we did good. We’re very pleased that these products are being so well received. At the end of the day, I want to do good work. Being part of making good tools is good work.

What’s next?

OK – over the next few weeks, I’m planning on running several blogs about How to Do Stuff in Blaze, Analyzer, and X-Edit that you may not know about. If there is specific stuff you’d like to know about, suggest. I’ll do what I can.

Mike is planning on doing Flare 4 stuff but he’s on the road for the next 2 weeks so that may be delayed a little. Be patient.

I’ll probably start Saturday morning, as I seem to like long blog postings on Saturday mornings. It’s quiet, in the house and in my head.

Finally and in conclusion

Char James Tanny is running a survey. We have no affiliation with Char. She sent this out and I think it’s fair game to post:

The Authoring Tool survey is still open! So far, the survey has had more than 300 responses from 18 countries. Keep spreading the word 🙂 Thanks!
The URL is http://www.surveygizmo.com/s/65623/tool-survey

The survey closes the end of September, so get over there and answer the 7 easy questions. It’s only going to take you a few minutes.

No one releases 4 products at once

Posted in Analyzer, Blaze, Flare, MadCap, Madcap flare, MadCap software, Tech Comm with tags , , , , , , on September 7, 2008 by Mike

Except us. That’s what we’ve spent the last month doing, getting all 4 products ready to release at the same time.

So what did we release? Here’s the list:

  • Flare 4 (author and publish online and printed content)
  • Blaze (author and publish printed content)
  • Analyzer 2 (free if you have version 1)
  • The X-Edit family (supports the multi-contributor workflow and eases the pain of reviews)

This is quite possibly our biggest release since the first release of Flare.

So what’s in the new versions, Sharon?

Really, too much to tell you about here. I’m going to send you to the brand-new website to find out more. It wasn’t enough that we released 4 products at the same time, we’ve also revamped and redone our website! (We’re all a little tired.)

Once at the new website, you can find out about all the new versions, sign up for demos and webinars, and download the trials. And send us feedback about what works and doesn’t work on the new website.

Did I mention the special pricing? We’re practically giving Blaze away.

If you’ve been waiting for…

A robust authoring and publishing tool that fits your workflow needs, it’s time look at Flare (online and print outputs) or Blaze (print outputs). If you’re still locked into chapter-based authoring, you need the power that topic-based authoring gives you.

If you looked at our products before and they weren’t quite what you wanted, take a look again. We’ve included feedback from our users, increased the power of the tools, and generally improved your workflow. It’s all there now.

Because good documentation shouldn’t be hard. (I thought up that tag line and I rather like it!)

My first podcast!

Last Friday, I did my first podcast. Tom Johnson and I spent about 45 minutes talking and I had a really good time. What you don’t know – and hopefully won’t hear – is that I was dying from food poisoning that morning. I’d been up since about 3:30a, pretty darn sick. I have no idea what I got into but it was in a hurry to leave.

Tom was great, as always, and I think it went well. I sure can talk. With luck, I made sense or at least entertained you. Maybe both! If I missed on both scores, remember how really sick I was and be nice.

Stop by and visit

OK – I’m expecting to see you all in demos soon. If you all want to show up, we’ll have to add a few more. But that would be happy news and not a problem. If you’re fast, I have a Blaze demo at 8am Monday morning, Pacific time. If you missed that, we’ve got lots of others.

I’m also going to be at DocTrain East at the end of October and then at Tekom in Germany in early November. I’ll be at several local STC functions and am available to come talk to your group about our tools.

Now go see what the excitement is about!

Happy Birthday, Son

Posted in Blaze, Flare, Madcap flare, MadCap software, Tech Comm, technical writing with tags , , , , , , , on September 2, 2008 by Mike

A few years ago today, the Saturday of Labor Day weekend, 2 weeks early, about 1:40 in the afternoon, I gave birth to my son.

Matthew Michael turns 30 today. He lives in Tulsa with his wife and 2 children and runs a photography business. If you are in the OK area and need photos, he’s your man. Click the Burton Studios link and see what he does.

If you like his site, he did it himself. He talked to my brother, the web god, and described what he wanted to do.

“Gee,” my brother said. “Most people use PHP for that.”

“OK, then I’ll learn PHP,” Matthew said.

So he did.

Did I mention that he has no formal training as a programmer? Yeah. He checked out a book from the library, looked up code samples on the web, thought about what he wanted the site to do, and started coding.

When he was 5, he started taking stuff apart to see how it works. Phones – *working* phones – were one of his favorite things to take apart for a while. Then it was off to VCRs and other stuff, just because he wanted to know what went on inside.

He rebuilt a car engine a few years ago because it needed to be rebuilt. “It was pretty easy, Mom. It’s obvious how it all goes together.” Apparently, my son “sees” how things must go together and then just does that.

This is the sort of brain this kid has. It was…interesting(!) to parent him. A strong visual, kinesthetic learner.

I’m a very proud mom. He’s the best thing I’ve ever done. Despite all the stupid stuff I did as a parent (and I’m sure he’s got a list), he turned out a good man. I’m delighted to know him.

Happy Birthday, Matthew! I doubt he remembers much of the day he arrived but I do!

In other news…

Another quarter of Fuzzy Ducklings has been set free. Bonni and I sent the Ducklings off last week and graded their finals over the weekend. No one cheated, at least that we could tell, and everyone passed. We had some great students this time and this was overall a good class. This group of Duckling engineers seemed to get the relationship between good documentation – spec, test cases, manuals, and so on – and the quality of the product.

We have 3 weeks between quarters before the next group of Ducklings come quacking in. Be nice to have the break.

By the way – our first group of Duckling engineers graduated last June. You may be working with them at some point. If they seem to value tech comm, you can send the thank you cards to me here at this blog and I’ll pass them along to Bonni.

Going with the X-Edit flow

We have exciting stuff going on at MadCap in the next few weeks. I thought I’d cover a little about the X-Edit family of products, to give you a little heads up about how we’re supporting your workflow.

The X-Edit family is 3 products in one, but it’s easier to think of X-Edit and X-Edit Contribute as 2 different modes.

X-Edit    Full featured word processor that also does everything the other 2 products do. Think of it as everything you could want. Saves to PDF, XPS, imports into Flare or Blaze, all that good stuff. Not a replacement for Blaze or Flare, because you don’t have the sort of topic-based authoring features you have in Flare or Blaze.

X-Edit Contribute    Lighter word processing features. You create a template in Flare or Blaze and then send that template to people who contribute to your projects. They open that template and start creating content with your styles, table formats, variables, if you allowed that, and so on. These files import seamlessly into your Flare or Blaze project. You can also do review topics, just like X-Edit Review.

X-Edit Review    When your Flare or Blaze topic is ready for review, you send it for review from inside Flare or Blaze. Flare or Blaze wraps all the stuff it needs for that topic and sends it to the reviewers you specify. The reviewer opens the topic in free X-Edit Review, makes edits or annotations, as you allowed, and then sends it back to you. You save it to your project, review the changes, and either make the changes to your source files or accept the changed topic into your project.

Common Tech Comm environments

As you know, the environment for Tech Comm people varies. I’ve worked with groups where the tech writers designed and wrote all the content. SMEs reviewed the materials for accuracy but never wrote a word.

But I’ve also been in the other extreme, where I didn’t write a single word – my role was to take the content from all the SMEs and wrap it into a tool to publish it. I was the tool expert, not the domain expert.

The X-Edit family lets you work at either end and in the middle somewhere. It fits your workflow, instead of making your change your workflow to fit our idea of what you should be doing.

OK, I hear you saying, so why can’t my content contributors write in Word and send me those files? I thought Flare and Blaze imported Word files?

Your content contributors can still do that, if that’s how you all want to work. We won’t make them stop if that’s what they’re comfortable with.

The advantage to the X-Edit family is that the content they’re creating is using your templates, your variables (if you want them to), your table styles, your everything, if you want them to have it. This means the content comes is very clean, significantly reducing any cleanup time and effort.

And the interface is pretty straightforward. And because you can specify what project features your SMEs can use, you can keep them from hurting themselves by misusing things like variables, conditions, and so on. They can be smart in their domain and you can be smart in yours. It’s a good match.