While I’ve spent my career in the software/consumer electronic world, I’ve done a little in the regulated industries. My favorite was working for a company that reported to the Federal Railroad Administration.

How is a regulated environment different?

It’s different in a number of ways, depending on who is regulating you.

For example, you may be lightly regulated, as the rail equipment company I worked for was. By this, I mean that you have to track things like the big edit reviews and resulting comments and all previously released product documentation. Design specs after a certain point had to be auditable, as did factory floor policies and procedures. As did training materials used to teach people how to use the products.

Fundamentally, anything that was required to show auditors how the product and the product instructions got be the the thing out in the field has to be tracked. And, because this equipment was very robust, they had to track it essentially forever, as the products worked in the field for at least 50 years.

If a railroad crossing failed and people or property were damaged, the company had to be able to show the documents that shipped with the products, how that information came to be in the manuals, how the equipment was made, and how the end users were trained to use the equipment. For as long as that equipment was functioning in the field.

They had a lot of paper in a lot of file cabinets.

What they all have in common

Regardless of the industry – FDA, Financial, SOX, Solvency II, other government – it comes down to audit trails. You have to be able to show the trail of content that got you to the place you are right now. And that means history of content development in some manner.

If you’re using Word or InDesign, you have to depend on an external document management system and somehow track when and how the changes came to be.You must track versions of what shipped and when to who and why. You have to track review comments.

You wind up with a lot of paper in a lot of filing cabinets.

There are better ways

There is another way – you can track and manage the components in your content. Using the right component content management tool, you can use the history features to show you this information. You can also manage your review comments electronically. It’s a lot easier than trying to manage all these parts on your own.

To see how Author-it manages history and audit trails, watch the movie below.

Have you worked in a regulated environment? What were the restrictions you faced?

Long ago, when I owned my own technical writing outsource company, we hired a writer for a project. She reported to my project lead, who wanted to tear his hair out after the first month.

She couldn’t estimate how much work was left. She also couldn’t estimate how much she had done. We had no idea if she was on track or not.

This drove us crazy, as we had a content spec for the project and her topics were clearly assigned. We also had a hard deadline. But for some reason, she was at a loss to estimate how many topics remained before she was done. She was a great writer but this was surprising. How do you not know where you are in a project? How do you know you’re on track for the deadline?

Release states help you

The thing I like about release states is they help you see at a glance what content is in what state. If we had used Author-it with release states, we could have asked her to count the number of topics that had been moved to review and subtract that from the topics NOT in review yet to get a sense of where we were in the project.

And they’re customizable, so you don’t have to try to fit your specific content flow needs into what we thought they should be. Release states support your workflow the way you need your workflow to run. Release states are easy to set up and easy to use.

To learn more about how this works, watch this 5 minute video from our free Learning Center.

I’ve been thinking about the use of social media and technology recently. We’ve known for years that people want the information they need to get on with things, whether it’s installing the new Blue-ray player or completing the vacation form for work. No one wants to read an 80 page document, complete with cross references and footnotes. Life is short and full of other things.

Alan Pringle (one of my personal heroes) has a new blog post that caught my eye. His main point is that “good” writing, for our users, may be indistinguishable from “good enough” writing. And I think I’m agreeing with him.

Close enough may be good enough

I’ve wanted to be a writer since I was old enough to understand that actual people wrote the stories I loved reading. I married a writer. I teach writing. I read like a crazy person. I write creative non-fiction. I’m very pro lovely prose.

But, do our users care that we labored over that paragraph for 3 weeks to make sure it read beautifully? I’m thinking not. Especially now that social media really is opening up ways for users to support each other.

For example, I bought a wireless repeater for my home network a few years ago. Because this is a 60 year old house, while it’s not giant, it has some challenges. Including walls full of metal piping and odd corners and areas that I’d like internet availability. I’d like to sit on my patio in the spring and fall and work on my computer.

The instructions for setting up the repeater didn’t work. Just flat didn’t work. I did an internet search, thinking I could not be the only person with this issue. Sure enough, someone posted on a list how to actually install this repeater. And the steps worked.

Were the user-provided instructions lovely and complete? No. Were they good enough for me to figure out the rest? Yes. I was up and running in less than 30 minutes. The informal instructions were good enough.

So what now, if we’re not the Keepers of the Well Written Information?

In the world of professional writing, the writing part is really a small subset of what we do. We design information, analyze audience, organize content, and anticipate user needs, to name a few. Clear writing is important but it’s not important enough to define what we do.

When I teach Introduction to Tech Comm, I teach a lot about a third writing, a third managing your projects, and a third “this is what we do all day”. So, clearly decent writing is important.

But if you can’t deliver on deadline, the writing doesn’t matter that much. If you deliver incomprehensible writing on deadline, it also doesn’t matter much. There is a middle area that’s the sweet spot for all of us.

Including our users.

If you are interested in a great conference, I strongly recommend the India STC conference in December. I’ve not been (yet), but hope to at some point. Apparently, the energy of the conference is amazing.

From their email

The 13th Annual Conference of the STC India Chapter will be held in Chennai on December 1, 2, and 3, 2011. Please send us a proposal with an abstract of about 250 words. Request you to include information about your profile in the proposal. If you have experience presenting at conferences, including STC, mention that in the profile. The best of the paper proposals stands a chance of winning a prize!

For information about paper proposal categories, visit: http://www.stc-india.org/conferences/2011/?page_id=18

Mail your proposal in .DOC, .TXT, or .PDF format to conferences@stc-india.org on or before August 5, 2011.

For more information regarding sponsorships and conference, drop a line to Saravanan Manoharan: treasurer@stc-india.org.

We look forward to meeting you at the Chennai conference.

Sometimes my personal life and my Author-it professional life collide. It feels like this is happening this week. The two stories are related – just stay with me on this.

Personal life first

We have owned a Leonberger dog for the last 2+ years, originally gotten to keep the Aussie company and be his best friend. She was about 6 months old when we got her and for about 18 months, all was well in my house. The dogs played together and liked each other very much.

And then something happened.

We don’t know why but the Leonberger no longer likes the Aussie and attacks him given half a chance. This has resulted in several massive scary dog fights. Because combined, they weigh more than I do, the fights were also hard to stop. And someone is going to get badly hurt.

So we hired the trainer we’ve worked with before and did everything she suggested – kept them separate, encouraged happy interactions, etc. All of it. Right down the line. We love these dogs and want to help them be friends again.

Seven months later, it’s not working. The Leo doesn’t like the Aussie. Period. The Leo likes other dogs very much but not the Aussie. The trainer says it’s personal. And personal means we are very limited with what we can do.

After thinking about what’s best for both dogs, we’ve come to the devastating conclusion that one of them has to find a new home. Because we had the Aussie first and because he has health issues, we decided to keep him and turn the Leo over to the local Leonberger Rescue.

The hand-over happens this weekend. There is a lot of sadness and crying in our house. But it’s the right decision, regardless of what we want or how much we love the dog. And we do love her.

Professional life

In the world of content development, we acquire tools and then often fall in love with them. Which is fine – it’s a happy place to love the tools you work with day in and day out.

But sometimes, the situation changes. Perhaps we discover the tool we love very much is not scalable and we’re growing. Perhaps we need a new output format and it’s really hard to get it, using this tool.

Things can change over time.

A new tool may be needed, But it’s hard because you really like the tool you have and it was such a good fit until things changed. You almost feel like a bad tool owner by changing tools.

But a smart professional understands the limits of what they are doing and recognizes sometimes you really do need to get new tools. It’s in the best interest of your content and your users to do so. It’s a hard decision to make but it’s the right decision in the end.

To help you make the decision, you may hire a consultant to advise you. If you do so, take them seriously. If you thought enough of them to hire them, then pay attention to what they recommend.

Why are these stories related?

In the end, you have to make decisions that are best for the situation, which may be very different than what you want.

I want my Leonberger to be best friends again with my Aussie. But that’s not going to happen, in the very experienced opinion of my trusted trainer (my consultant). As a result, both dogs are stressed and potentially I or the dogs are going to be badly hurt.

You may want your tool to work for your group after you add 10 more people. But if the tool was never designed for what you need now, then it’s the wrong tool. You can pretend this is all going to be OK or you can face the facts and make the right decisions.

It’s up to you.

Regardless of what you exactly do in the field of creating or producing information, you spend time developing content. For most of us, that means writing but some of you do screen videos, or make illustrations.

I’ve come to realize in the last 2 or so years, we need to stop calling this writing, or drawing, or what ever and refer to this process as “developing content”.  And I have some good reasons.

Developing content

There is the thought out in the business world that “anyone can write – we were all taught in school how to do it.” And that’s a silly idea. In school, we were given the tools and shown how to use them.

• We got a hammer and learned to pound on things.
• We got a screwdriver and learned to turn things.
• We got a wrench and learned how to wrench things.

But very few of us left school knowing how to build things. So why does the business world think we all did? For some reason, the business world thinks that all you needed was an introduction to the tools and you’ve got the skill.

They don’t think that about managing their financial books. We all can basically manage a household budget but probably none of us are suited to be a CFO.

Writing is a skill and a gift

Most of us professional writers started with a gift and spent a long time learning our craft. We improve and improve to the end of our lives.

Much like a carpenter (to continue my metaphor) who starts with a gift and learns more and more over the course of his or her life. The work of a master craftsperson is breath-taking in its beauty.

So, if the business world thinks that what we do is essentially unskilled apprentice labor and that anyone can do it, we need to reframe the discussion.

Developers make stuff

My reasoning for content development is that developers make stuff. Perhaps in your company, they develop code.

We make stuff, too. And our stuff is as important and needed as the code is. After all, if you can’t use the product, what good is it?

Therefore, we’re content developers. We develop content, regardless of writing, illustrating, or anything else we’re creating to support people in what they are doing.

Try it out

Try it out in your workplace. Start quietly calling what you do “developing content”. Don’t make a company announcement or anything. Just start using the phrase. I bet in 6 months, it’ll come back to you from someone else.

Do you agree there is value or do you think this is silly semantics?

We are in the business of getting people the information they need and letting them get back to their life. Fundamentally, that’s what we do, whether we write user manuals, policies and procedures, create illustrations, videos, or any other thing.

And in this information rich world, this is an important thing to do.

No one reads the manuals

If I had a US dollar for every time I’ve heard “No one reads the manuals” I’d be retired in the tropics, playing with large dogs and writing crazy stories. While no one reads the instructions is a true statement, it’s a false statement.

People do read the instructions we provide. They do. But not like a novel – when was the last time you read your employers Policies and Procedures guide, start to finish? Probably never. It’s not that interesting.

But you may have read a part of it in the last month – perhaps when you completed your expense report for attending the STC Summit conference. Because you couldn’t remember what the per diem was and how to charge that properly. Because you don’t fill out expense reports often, you needed to be reminded of how to properly do that task. So you could get on with your life.

And that’s how it works

This is how our instructions are used – on demand. People rarely read our instructions from beginning to end, to see how it all turns out. Typically, people read what they need to know right now and then move on.

Perhaps they need to refresh their memory about how to run the month-end report, or how to rewire the speaker wiring for the home theater system the 3 year old gleefully pulled out. or they need to create an expense report.

So how can we help?

We can create short, to the point instructions for these user moments. I call them Job Aids, you may call them something else. But they are short overview instructions for important infrequent tasks.

Installation is a good job aid – typically called Getting Started guides. For most things, you install one time and then never again. You probably don’t reinstall your garage door opener – after it’s complete, you can happily throw away those instructions.

Other tasks that make good job aids are running end of month and end of year reporting. Not done often enough to remember exactly how to do it so a refresher is helpful. You probably don’t need to include how to run a report, because reports may be run at the end of every day. How to set up the end of year report and archive the data is similar but different.

Make them available to your users

OK, so if my users only need these infrequently, how do I get that information to them, you may be asking yourself.

You can ship them with the product, if you know ahead of time what is needed. But most of us don’t have the luxury of knowing ahead of time.

If you talk to your support people, they can give you ideas. Many of the questions they get are actually Job Aid questions. So talk to your support people and see if they get the same sorts of questions.

Then develop the job aid. Try to keep it to one sheet of paper, front and back.

Now you can post the job aid in the support area of your website. Ask support to tell callers about them. If you send a marketing thing to your users every month or so, include links to the newest job aids to get people to know they are there.

Job aids can impact the company’s bottom line

Consider tracking statistics to see how often the job aids are looked at/downloaded and if those sorts of questions are being asked less often in Support. That’s how you know you’re being effective. Take those numbers to management as clear evidence the docs group is making a bottom line impact on the business.

Clearly someone is reading them, you can say. As a matter of fact, this month, X people read them. And Y people didn’t call support to ask about that topic, as compared to 6 months ago.

This has been a very busy week for the technical content world.

Author-it 5.5 is released

As you know by now, we released the latest version of Author-it 5.5 to great excitement in the industry. Once again, we’ve redefined the possible in the content authoring and managing world. For more details about what this release includes, click here and then sign up for the free webinar that shows you how the Author-it Reviewer works.

June 1st at 2pm Pacific. As always, if the time or date don’t work for you, sign up anyway to get a link to the recording the next day.

This hour long webinar is a don’t-miss event. We strongly recommend inviting your boss as well. S/he’s going to want to see this. Author-it Reviewer is changing collaborative work forever.

Author-it Learning Center

If you’ve been interested in learning Author-it, we have an option you’re going to love: free, on-demand training.

The Author-it Learning Center includes videos to help you understand the basics of Author-it. You learn what objects are, how to import and author content, and how to customize your outputs.

It’s all online, ready for you to view when you’re ready to learn. Each session is under 15 minutes, making is easy to find the time to learn something new.

Even if you know Author-it, it’s a great way to refresh your skills or review something you may have forgotten. What a great way to get the information you need and move on with your day.

The STC Summit Conference

And finally, this week was the STC Summit Conference. We want to thank the many many people who came by the Author-it booth to find out how our products can make life easier.

150 people wore Author-it tee shirts for the special Apple iPad give away. We talked until we had no voice, gave out chocolate Kiwi Fish, and awarded the iPad to Andrea Wenger.

A great time was had by all, as you can see in the picture below.

I was away last week at a client site, working with them on how to move to Author-it. They bought Author-it because they see the benefits, but, like a lot of companies who are looking to improve their workflow, they didn’t really know where to start. What would be Best Practices for them? How to get there fast so as to not interrupt the current deadlines?

They also wanted to use this move to better architect their content so they got more value out of what they have.

And so we started

We started with looking at the content they had and how they currently use it. They sell large industrial machines that are sold either 1) “as built” with no customizations, or 2) somewhat to extremely customized. They don’t do online help, so we just looked at producing PDFs. Of course, if they need to someday move to help, that’s super easy for them.

They had been doing docs in InDesign and Ventura and had to copy, save, edit, and rebuild every time a customer wanted a manual 2 type. This process took 1 to 3 days, not counting any new content development or any review time.

What they wanted to know was how to go about this process in Author-it. We walked through how to build a book and  then use variants to create the custom books. They got very excited that the 3 days of production would be reduced to less than a day.

Importing existing content

Then we started importing content from Ventura and InDesign to see what that was going to involve. It’s one thing to get new tools to improve your workflow, but if getting the content into the new tool is hard or impossible, that’s something else entirely.

The good news is that getting the content in from Ventura turned out to be super easy – we had the profile set up in under an hour. This is in large part because the docs staff had stuck to a short list of paragraph formats and didn’t play fast and loose. One of the advantages to a team that has been in place for many years is this sort of rigorous adherence to the templates.

The InDesign docs, however, are a different story. People in and outside the docs group created the InDesign docs. The adherence to the template was, well, less strict. We got the basic profile created pretty quickly, but there is going to be some pre-import work needed to put all the text in InDesign into one flow, instead of the adhoc flows it is in now, for example.

Changes to the workflow

Then we started looking at the workflow issues they needed to change to make this all work. The specific details for them are not important to us here, but the big picture is.

They needed to review how they:

• Import existing content – release states to know what’s been roughly imported, reviewed after import, ready to start publishing, and so on
• Develop content – what is truly new content and what should be reused, where to put content, how to know it’s ready for reviews
• Manage existing content – version, variants, release states, and so on
• Structure and locations of graphics folders- where to put overall graphics, product line graphics, one-off graphics, and so on
• Reuse content – what can be reused vs what is currently being reused, where to put reused content, how to name it, and so on
• Review content – how do they send out just the content that actually needs to be reviewed vs all the content in a manual, and more
• Manage localized content – they don’t do a lot but when they need to they need to right now
• Archive content and understand the history – what topics shipped in what manuals when? When was that topic changed and to what?

In sum

Even if you’re not thinking about moving to Author-it, these are all issues you must face when you move from one tool to another. You certainly can just start dumping your existing content into the new tool, but I think that many of the problems you had with the old tool are still going to be problems in the new one.

It takes planning and work to get the benefits of moving to a tool better suited to the problems you’re trying to solve.

I applaud this client for thinking this through and planning the change. It shows real maturity and that the CEO understands the value of their content.

I was really excited to work with this group and know they will be successful.

A visual

I’m including a photo I took the one warm-ish day I was there. My hotel was right on the Spokane River. One day was sunny and I took a long walk along the river to clear my head after a full day of intensive work. It was great. Being a So Cal girl, I don’t see many rivers. Ones with water, anyway.

(The client was not Kaiser Aluminum, I just liked the lovely river area with the Kaiser plant above the river.)

As I’ve stated before, I’m not a strong visual learner. I like words and getting my hands on things. But many people are strong visual learners and I need to accomodate them in any content I develop. So, since I like words, I found a book that helps me with visual information. I thought I’d share some highlights with you in case you’re also not a strong visual learner.

By the way, to find out your learning strengths, take the VARK quiz.

The book is a classic: William Horton’s Illustrating Computer Documentation. Wiley Press, 1991. I realize it’s older but the concepts and principles are valid regardless of when it was written. If it’s not on your shelf, I strongly recommend you get it. Mine is dog eared and written in and tagged all over.

Design content for scanning

Since I like words so much, I was delighted to discover that words can be graphical elements, too. Lists and tables are visual and need to be designed as such to support your visual learners.

While tables are inherently a grid, you can make tables harder to read by using horizontal AND vertical lines. Pick one (and you may not even need that) that suits the information and stay with that. Make any lines thin enough to let the eye follow but not thick enough to visually draw the eye.

Since humans are hard wired (because of the rods and cones in our eyes) to see lines, we want the thickness of the line to not overwhelm the visual field.

Lists are always a good thing to use. If you use lists, make sure they are used correctly.

1. Numbered lists imply steps.

• Bulleted lists imply a lack of order.

• Check box (which I can’t figure out how to show you here) lists imply completeness.
  • If you use several levels of lists, use a different bullet for the other levels

Organizing content visually

Screen captures are good and we all use them, assuming you’re developing content for software. But think about how else you can visually show information.

For example, the last time I was documentation manager, I instituted a policy that every chapter (section) must have an introductory paragraph(s) and then a graphic that illustrated the ideas in the paragraph(s). This supported both our word learners and our visual learners. It visually organized the content in that section.

Typically, we had a flowchart, showing information flow through the system but sometimes we showed how parts worked together. It depended on the content in that section. We single-sourced that graphic to the online help to support the different learners there as well. Had we the time and the staff, the graphics might have become animations online.

On a different note

Don’t forget to go to Facebook and Like the Author-it page. At the STC Summit, we’re doing a special drawing from the list of Facebook Likes and giving away something very Kiwi. You want to be in that drawing, even if you’re not at the STC Summit.