Visionate document linker drives productivity and quality


Abstract

The Visionate document linking template provides business analysts and systems analysts with the capability to create well structured documents whether for business or technical stakeholders, that are easily understood and assimilated, and fast to create.

Documentation principles

The Visionate approach to documentation is based on principles designed to support the Lean-Agile-DevOps concepts of enabling the effective flow of work through the system, and the shortening and amplifying of feedback loops.

An element of this is to have standards-based approaches to documentation with a separation between the process elements which describe the flow and specification elements which comprise the business rules.

This approach makes for documents which are easily understood, and which have a direct link to testable acceptance criteria.

The link between processing and specification is enabled in MS Word by making use of the powerful cross-referencing capabilities that MS Word makes available.

Visionate Linker

The downside to the approach is the number of clicks that the analyst must go through in order to set up the cross reference.

Using the standard MS functionality for cross referencing it takes a combination of 32 mouse clicks and keystrokes to create the following linked text:

(See section 6.3.7.1 'Functional Business rule one' on page 12)

The Visionate Linker creates the same linked text with three mouse clicks, as shown in the image below.

The Visionate hot linking template provides a simple UI that allows analysts to create their links, in a standard predefined format, with a minimum of effort.

Installing the Visionate Linker

Extracting the template

The Visionate Linker requires two installation steps to set up for your PC.

The first step adds a custom form and a small piece of code to your ‘normal’ template

The second step is to set up two clickable buttons in your Quick Access Toolbar

The template document NormalMacros.dotm contains the form and code to run the linker. It is downloadable as a zip file from the link below.

The word template document has code in it, and you are rightly to be concerned about running it on your PC.
So before running it, make sure you right-click, and scan the item with your antivirus software

Once it has passed the scan, unzip the file to reveal the NormalMacros.dotm document

Add Macros to MS Word

  1. Open Word on your computer
  2. Click the View tab, select the Macros icon, and select View Macros.

At the Organizer window, click the button on the left side to Close File.

The same button is now renamed to ‘Open file’

Click to open the browse screen

Locate the NormalMacros.dotm file and select it

The form will populate with the available macros

Select macros and copy to the right hand side pane – for the normal global template

At this point you have the macros loaded and available to you. The next step is to set up the buttons on the Quick Access bar

Setting up the Quick Access Bar

The quick access toolbar is at the top left of your MS word document

Select the down arrow to customize the quick access toolbar

In the Word Options screen – select the dropdown box and then select macros

Select the macro (assignref) on the left hand side then press the add button to move it onto the quick access menu

The menu item will have a default icon. You can change it to something more meaningful to you

The back arrow is a standard command available under ‘Commands Not in the ribbon’. Add it in the same way as you added the assignref macro

At this point your system is now set up to use the Visionate linker. Use the back button to efficiently navigate through your document.


Constraints

Please note that the usage of document linker in Word has some existing constraints.

Long pathnames

The ‘Back’ button in MS Word does not like long pathnames. This can be a problem if you are storing your files on Teams or SharePoint with very long access paths. You can address the issue by shortening and simplifying your pathnames and filenames.

Tracked Changes

The MS word cross referencing, which the document linker is built on, can get mightily confused by having tracked changes turned on. It has no problems with comments. The workaround is not to use tracked changes to mark version alterations, and instead use highlighting. You always have the ability to compare versions with previous documents so tracking in not usually necessary, and also highlighting is more user-friendly than a mass of tracked changes.

Relies on headings

The set up of the document linker relies on headings being set up in a certain way with numeric nesting of different heading levels. It still works fine but without numbering it makes selection slightly harder in the selection screen and also the formatting of the link has a slight issue.

In the lines below the first is with standard numeric formatting and the second is without numeric formatting

  • (See section 6.3.7.2 ‘Functional Business rule two’ on page 12)
  • (See section 0 ‘Functional Business rule two’ on page 12)