FLOWiki

(y)our wiki about all things technical communication

User Tools

Site Tools


word:using_updatable_text_snippets

Re-usable text snippets

Introduction

As a technical writer, you can use one of the following programs:

  • Professional authoring tools such as MadCap Flare.
    They are very practical programs with many features used by technical writers.
  • Professional authoring tools using DITA like oXygen XML editor and Adobe FrameMaker. DITA is an XML architecture and an OASIS standard for designing, writing, and publishing information.
  • Freeware like DokuWiki or Texmaker. These programs don’t have professional support but there is a great community which will give all the support you need.
  • Text editors like Microsoft Word. This is a simple and effective way of writing a document, but lacks many features of professional authoring tools

This article is about content reuse in Word.

Problem

General

In technical writing, often some content needs to be reused. Sometimes the same piece of text needs to be used in multiple parts of a book or in multiple separate documents. These reusable pieces of text are called snippets or chunks. Reusing chunks of text can be useful if you have multiple documents where the same paragraph of text appears and you want this paragraph to be updatable.

This document will show one way to insert updatable text in Word. This method described for Word is not perfect, as Word is not really meant for content reuse. Feel free to comment on the method described here in the discussion.

In DITA, this can be done using conrefs. Conreffing a piece of text is a great and simple way to increase content reuse. It is also more practical than in Word, but of course, many of our customers still use Word as their primary text editor.

Case

At Flow, all employees make a resumé in Word with the same company layout. In the document the employees describe the training they have received on the job. The company specific training comprises of a few different modules, and not everybody received the same training courses.

To make it easier to insert the right courses and to keep the texts up-to-date, we want to use snippets.
First, for each training module, we create a source text in a repository. In a later step, we then insert the snippets into the resumés, while keeping the link with the source text. If you open the source text and change its contents, the descriptions in the resumés will be updated.

Method

Take these steps to solve the problem:

Create the source texts

  1. Create a folder which will be the repository where we store the snippets.
  2. Open Word and create a new file based on the Flow-template, store this file in the folder you just created.
  3. Edit the document to contain the text you want the snippet to contain.
  4. Save the snippet in the repository folder.
  5. Continue making snippets and storing them in the repository folder (repeat steps 2 to 4).

An example of a snippet:

  1. In the Word ribbon, click the Insert tab.
  2. In the section Text, click the arrow next to Object and select Text from file
  3. Select the file containing the snippet you want to insert.
  4. Click the arrow next to Insert and click Insert as link.

The text is now inserted inside your document (in a text field), while still referencing the source file. When the source text is now edited, all references will update too (using the method described in 'Updating the field’).
Below you find an example of a text field (highlighted in grey) referencing the source text:

Tips and tricks

Updating the field

To update a field, place your cursor inside the text field (it becomes grey) and press F9. Alternatively, right click on the field and click Update field. If the text field doesn’t become grey, edit the settings as indicated in Editing field Shading.

Editing field shading

When you select referenced text it becomes grey-shaded. This is called ‘field shading’. If it doesn’t turn grey, edit the preferences:

  1. Go to File > Options.
  2. Click Advanced. A panel opens with all Word options.
  3. Find the section Show document content. Here the option Field shading should have the value When selected or Always. If this is not the case, change the option to one of these values.
  4. To leave the dialog, click OK.

Field shading is now enabled.

Sending the Word document to other people

People without access to the referenced files cannot update the fields. When trying to do so, they receive an error…

To avoid this, send a PDF document instead of a Word document or do the following:

  1. Click File and look in the lower right corner for Related Documents.
  2. Under Related Documents, click Edit links to files.
    Now you see all links to other files in a new dialog.
  3. Click one of them and select the Locked check box.
    The Update Field button is now disabled.
  4. Repeat step 3 for every link.

The file is now ready for sending.

word/using_updatable_text_snippets.txt · Last modified: 2017/03/31 13:38 (external edit)