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.

Regardless of where you are in the world, we at Author-it would like to wish you a Happy Easter weekend.

For people in New Zealand and most of Europe, you have a 3 or 4 day holiday. It sounds like a great time to spend with your family, napping, or what ever makes you happy.

In the US, we don’t get any extra time off from work for Easter, but, as my Kiwi cohort mentioned yesterday, we do get Thanksgiving in November as a long holiday. For my cohort, the similarities are both long holidays are late Fall, early Winter for the local residents.

Something fun

As something fun, if you are attending the STC Summit in May, go to our Author-it Facebook page and Like us before May 17.  We’ll do a drawing in the booth at the Summit from the names who Like us and give something away.

Winner will be announced at the booth, on twitter, and Facebook. You don’t need to be present at the booth to win but if you are, you can take the prize with you right then.

Don’t forget the exciting webinar Monday the 25th

Don’t forget the exciting webinar next week: Content Development: Future Trends, Future Solutions Webinar, presented by Paul Trotter, Founder and CEO of Author-it Software Corporation. We have a lot of people signed up but we’ve got a little more room.

We will be recording this webinar. If you can’t attend because the date or time don’t work for you, sign up anyway. An email with a link to the recording will be sent to everyone the next day.

Whether it’s Spring or Fall where you are, enjoy the weekend and we’ll see you next week!

I, like most geeks, am always happy to learn more about space programs. Recently several friends went to Houston and the Space Center there. They met astronauts and did other things I’m deeply envious about.

One of my friends took pictures of the documentation for the space shuttles that I thought I’d share. Click here to see the pictures.

Why do we care?

The shuttle people are very smart people. So the actual instructions are probably written at a high level of knowledge because you can trust these smart people to know a lot.

But what I found interesting was, as my friend wrote,

the formatting and layout of these. The books are printed in a large, san-serif font on card stock. The binding is open rings, so they’ll lay flat without any argument. Remember that 95% of the time, these are going to be in zero-G, so any slight tendency of a book to snap shut (from a perfect binding that would normally be fighting against gravity) would cause the book to close.

The page layout is very loose and open, and could be written on with a pencil easily. The blue tape is velcro (NASA just lives for velcro!). As you can see in some of the later pix inside the shuttle simulator, the books are velcroed in place everywhere so they can be seen easily.

Audience is everything, except when environment is everything

So, not only do we need to think about what information  our users need, we also need to think about how and when they will be using this information. Most of us are not designing information to be used in space, but what an interesting problem to solve. And what an ugly but perfect solution they found. (You have to admit, the blue velcro is ugly but very visible.)

Talk about tailoring the information delivery to the needs of the audience!

What unusual environmental information delivery problems have you solved?

If you’re working in a typical document-centric content development environment, you probably manage versions of product documents by copying the entire previous document(s), renaming to the next version and go from there. While this seems like a good way to manage versions, problems can arise, including how to find and manage all the copies floating around your source control or internal network.

And if you need to compare what content applies to what version, life gets really complicated. You can use the built-in document compare but for some products, variables and cross references count as changed text, not really giving you the picture you need.

You could always print out the compared document and do a line by line manual highlight of the actual changes. Unless the document is more than about 100 pages because who has time to do that for the 30 documents you produced 3 versions ago? And then you’re stuck with paper trails you need to manage. It’s a very cumbersome process.

There has to be a better way

A better way would to be able to assign a version to the content when you create it. That would at least show you somehow that this topic was added for version 3.1 and that content appeared in version 4. You would have some sort of audit trail to see what appeared or changed and when.

Building the output could get complicated, though. If you want just the content that applies to version 4, you would have to somehow include the content that didn’t change since version 2. But you don’t want the version 3.1 content, just the content for version 4 and the content that hasn’t changed since version 2.

You would have to mark content as valid for version 2 and 3 and 4 and 4.1 and… That sounds cumbersome, too.

Maybe an even better way

An even better way would be if you could somehow specify you want version 4 and the publishing system programatically looked for all version 4 content and gathered that up. For content that isn’t marked version 4, but appears in the list of content you want to publish, maybe the system could walk back versions to find content.

That way, the system tracks things down and you don’t have to manually assign multiple versions to the content, which you’re going to forget to do.

Computers are really good at tracking things. Why don’t we let them do that part and we can create the content?

It’s a better way

Environments that are regulated, such as financial or medical, should like this approach. This even better way of versioning let’s you easily create the documents as they were for each point in time so the auditors can easily see what they need.

Environments where your technology has a long life span might also like this versioning method. For example, if your technology is still in the field and still working 20 years later, you may need to create documents for it on request, even though that version is 20 years old. With this even better way of managing versions, it’s not a problem – simply specify the version to start with and the system does the rest.

Sound interesting?

By Sharon Burton

The weather here in Palm Springs is lovely. Warm sunshine to sit in a drink coffee. Which I did this morning.

The booth is almost set up – I’m missing 2 boxes and am tracking those down. Since it’s all my marketing materials, it’s sort of important!

I’ve already run into people I know who are here for the pre-conference workshops. Hugs all the way.

The Intelligent Content conference looks to be great!

Tom Johnson just wrote a blog post I rather wish I’d written. Great work!

Find it here: http://idratherbewriting.com/2010/10/22/why-help-content-fails-contentstrategy/

One of my tasks at Author-it is to help us better explain what we do. I’ve spent some time this week, looking at our products and trying to come up with a coherent way to talk about them.

The best way, I decided, at least as a start, is a table, showing tools across the top and interesting things the tools do on the left column. It’s a pretty standard information design layout, nothing invented here, if you will. But I thought it might clarify what we offer.

Help

Then I asked for help from others to identify the things our products do to go in the left column. That’s where life got interesting.

Because I work with very smart people, I started getting all sort of information. I accepted it and added it to the table. But it wasn’t the right information. I wasn’t sure why it wasn’t right, I just had that vague feeling: there’s an issue.

After about two days, the list of things was pretty long and I was getting pretty lost. I put it aside to work on other things, knowing I’d be back to it.

Sleep is good

I was almost asleep that night when it hit me – the reason the information was wrong wasn’t because it was bad information. It wasn’t audience appropriate. (This says far more about how much I think about work than it does any brilliant insights I might have.)

We were creating a list of all the features of the products instead of focusing on the information the table was trying to show – what products do you need to do what big picture stuff?

With the user in mind, I took my editing hack saw and starting cutting. I cut about three quarters of the content.

The list is in review

So, the list is in review now. When it’s done, expect to see it on the website. It should help you clarify what you need when you decide to move to our products.

It really struck me that despite my constant focus on my audience and why the audience cares about the information, I can still get led down a garden path. Thank goodness I was willing to trust my vague feeling. Sometimes, when you’re creating and designing information, you have to play with it and look at it before you realize what the issue is and then how to fix it.

Any other ideas about how the website can be clearer/more helpful? I’m happy to hear them!

I came across a question today on LinkedIn asking “What’s stopping the wider use of DITA within your company?”.

Some of the responses that were given included reasons like

• I don’t have time right now to do this
• I did this at my last job, and it cost me my job
• Too hard to migrate content to DITA
• Too expensive to buy the tools

What really surprised me was that I don’t think most people really understood the question. I believe the question was asking, what is stopping other departments using DITA, not what is stopping more technical writers on more projects using DITA.

In my experience, which is very broad, the key factor that is “stopping the wider use of DITA within organizations” is that DITA is a content model designed to meet the needs of producing technical product documentation, more specifically software documentation and is not applicable, or even easily adapted outside that use case. DITA was after all designed by IBM to meet their internal requirements and has not changed much since entering the public domain.

The other major factor is that outside professional writers, like technical communicators, users lack the skills, discipline, and desire to be able to understand or use the complex set of technologies and tools required to make DITA work. It’s simply too hard.

To make matters worse, even professional writers struggle with DITA and many organizations are abandoning their DITA (and other XML) implementations in favor of less complex and more user-friendly solutions that can be easily adopted across the organization by users of all skill levels.

Last year we replaced dozens of DITA and XML based implementations with Author-it, in large and small companies alike. I remember meeting with one particular group that had been working with DITA for about a year and was very adamant that it was the only way to do it. During the presentation of Author it we showed them how easily they could migrate their DITA content, do everything they were doing with their XML based tool set, and much more, while continuing to use the DITA content model and validation within Author-it. Needless to say they are now happy Author-it users.

Paul Trotter
Founder and CEO
Author-it Software Corporation

I had a conversation today where I was discussing strategies for content architecture with a Fortune 100 high tech company. The person I was speaking with stated that they wanted to create a strategy where the content was completely independent of the tool set used to create and process it.

I believe his premise was that by making the content tool agnostic, that it enables independence from tools, and allows different parts of the organization to choose different tool sets independently to meet their specific requirements. Provided all the tools can magically inter-operate and just load and save the content in the same model everything will be wonderful.

So my question is. Is this really feasible, or is it just a flight of fancy?

My opinion is that if you are focused on satisfying the actual business requirements of users who are authoring, managing, translating, and publishing that content you cannot practically separate the tools from the content because the requirements themselves are not satisfied by either the content model or the tools, but the combination of both.

This is why you never see this type of separation in other software categories like CRM, Financials, or ERP.

If your organization was looking for a new CRM, would they design an independent data model and strategy around managing client information, then find tools that will use the model? I doubt it.

Instead they would most likely gather their business requirements, which by definition need to be independent of implementation, then go to the market with an RFI or RFP. This enables them to consider all the possible ways and technologies available to solve their problems.

I would love to hear your opinions and feedback on this subject.

Paul Trotter
Founder and CEO
Author-it Software Corporation