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
Installation Overview
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
1. Download and unzip the NormalMacros template
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.
2. Scan the download file
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
3. Extract the template document
Once it has passed the scan, unzip the file to reveal the NormalMacros.dotm document
Add Macros to MS Word
1. Open MS Word
- Open Word on your computer
- Click the View tab, select the Macros icon, and select View Macros.
2. Open the Macro Organizer
3. Close existing macro location
At the Organizer window, click the button on the left side to Close File.
4. Open location for NormalMacros.dotm
The same button is now renamed to ‘Open file’
Click to open the browse screen
5. Select the new template file
Locate the NormalMacros.dotm file and select it
The form will populate with the available macros
6. Select 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
Location of Quick Access Toolbar
The quick access toolbar is at the top left of your MS word document
1. Open to customize
Select the down arrow to customize the quick access toolbar
2. Select to see macros
In the Word Options screen – select the dropdown box and then select macros
3. Set an menu item for the macro
Select the macro (assignref) on the left hand side then press the add button to move it onto the quick access menu
4. Modify the icon
The menu item will have a default icon. You can change it to something more meaningful to you
5. Now load the back arrow
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)