How can I create technical documents or web content that gets updated on the fly?

Doc-2-Help is the ‘other’ help authoring tool. RoboHelp may steal the headlines but Doc-2-Help has many hidden features that make it an essential tool for technical writers, especially those involved in writing online help or web content.

How to create content dynamically

This week I’m going to show you how to create content that can be updated on the fly.

This is also known as conditional text in that the condition is setup to appear ‘on the condition’ that it is needed by an application.

Give me an example, dude!

Why create dynamic content?

Ok, say you have a product ‘Hysteria Hamsters’ that is on Version 3.0. But you also have a legacy version 2.0 and other smaller releases, 2.1, 2.2 and 3.1. You get the idea, right?

You now have a choice. Develop a manual for each version (that’s at least four) or create one master document and then create ‘variables’ for each different version.

Which one do you prefer? Thought so.

How do I create dynamic content?

Let’s use Doc-2-Help to do this. There are other ways, including our friend Adobe FrameMaker and XML but let’s look at this puppy for a second.

Tip — don’t create one master document in Word. Instead break it into chapters or topics (aka chunks) that are easier to manage.

Nicky Bleiel over on the Doc-2-Help site gives this advice:

• Chunks can be long or short and they have two added benefits
• Content only needs to be updated in one place, no matter how many times it is used within a project.
• It ensures consistency, since core information will be the same within and among projects.

Nicky adds: “take a look at your content and determine what pieces are used over and over.”

Some common software documentation examples include:

• Product Names
• Field/checkbox/other UI definitions
• Product descriptions
• Terminology definitions

More wise words from Nicky at: http://forums.componentone.com

How to create dynamic content in Doc-2-Help

To do this in Doc-To-Help, we use Variables.

• Use Text Variables for short pieces of text, such as version numbers, copyright clause, author names and so on.
• Use Rich Content Variables for chunks of text that may require formatting, for example, instructions with bullet lists.

Get the idea?

Tip — Give Variables meaningful names. You don’t want to waste time figuring out what they mean or explaining it to another technical writer who joins the team. Avoid spaces in the variables.

To create a Text Variable

1. Open Doc-2-Help.

2. Click the Project tab and then Variables button.

3. In the Text Variables area, click the Add New Variable toolbar button. A field named “New Variable” appears in the Name column.

4. Enter a name for the variable and then double-click Variable text to enter the text.

Tip — you can assign one or more conditions to a Variable.

To create a Rich Content Variable

1. Open the Variables window.

2. In the Rich Content Variable area, click on the Create New Document button.

3. Choose XHTML, HTML, or Word Document from the drop-down list.

4. When the Save New Document As dialog box opens, enter the document Name and click Save to add it to your project.

5. Double-click on the document name to open it, for example in Microsoft Word. The Variables document displays a table with two columns.

6. Enter the variable name in the left column — remember, no spaces! — and the variable content in the right column. Jazz it up if you want with styles, including conditions.

7. Save it.

How to insert variables in technical documents

In Microsoft Word, the Variable button is located on the Doc-To-Help tab on the far right.

1. Open the document and find the place where you want to insert the variable.

2. Select the text that you want to apply the variable to and then click Variable.

3. Choose the variable from the list in the Variable dialog box.

Note that the text changes to red when the variable is applied.

Once you’ve got the hang of this, you can start using variables across all types of documents.

I’ve started using them to update my website, so that content on different pages is tailored to different readers. It’s very powerful once you start using chunking to create documents based on topics.

I hope you found this useful.

It’s made my life as a technical writer much easier.

What do you think?

Have you use variables or conditional text on your documents? If not, what’s the barrier? Is it how the he content is written or the tools you have to use?

Related posts:

1. How to Save Word 2007 Docs into Word 97-2003 Format Microsoft Office 2007 saves files in the .docx format, whereas...
2. Save a Word document as a PDF – No third party software required Download the free plug-in for Microsoft Office Word 2007, so...
3. Create a document for use on previous Word versions To create a document that will be used in a...
4. How To Write Blog Posts Faster & Save Your Fingers From Exhaustion What to know how to type faster and get those...
5. Review MadCap Mimic 4.0, Reuse your Existing E-learning and Training Content MadCap Mimic 4.0 is a native XML application designed for...