Technical Documentation

Overview

This content of this project has been migrated from MS Word documentation which was extracted from published Articulate output. The following modules are included in this project :

Creating & Managing Customers & Sites
Creating & Managing Users
Creating & Managing Machines
Events & Alarms
Price Cards
Data Discrepancies
Site Support Role
User Audit SOX Social Compliance

All modules are created as separate folders in the Content folder, with each module having a corresponding TOC (Table of Contents) and a Target.

The following are the default documents used in this documentation.

Topics (htm), Tasks and Articles

These are the pages where the content is updated or when creating a new topic.

Stylesheet : Tasks.css

MasterPage : Default

NOTE | Each module in the Content folder contains a file named 'Template' which can be used when creating a new topic. This file should then be renamed using preferred file naming conventions.

Home Page - Main

Each module has a page named 'Home' which contains the 'hero image' for the module. A Home page is also available in the main root directory of the Contents folder.

Stylesheet : HomePage.css

Masterpage : HomePage.flmsp

Master Page

The Master page is the template for all topics, tasks and articles in this project.

There are 3 proxies in the Tasks master page, shown below. Proxies are blocks which represent standard features which will appear on all pages, excluding the Home pages.

Proxies in the Master page

On-Page Navigational Elements

This page navigational element is contained as a proxy within the master page and is an self-updating navigational element. Each page, with the exception of the Home pages contains the Previous and Next page navigational elements (topic toolbar proxy) shown below. These navigational elements synchronise with the TOC entries and are not required to be updated when pages are moved.

The styles within the proxies can be updated by right-clicking onto the proxy in the master page and selecting the relevant proxy.

New proxies can be inserted into the master page by selecting the Insert > Proxy option in the Flare menu bar.

Targets

Targets in Flare are required in order to output the topic content to different formats or to specific publishing requirements.

Primary Stylesheet : Default

Template Page : Tasks

NOTE : On receiving this project, each Target output destination must be changed to a local destination. Select Projects > Targets > (select target) > General > Output Folder.

Stylesheets

Each topic requires a Stylesheet to determine the overall appearance of the documentation. Stylesheets are also used to provide consistency over the entire documentation in terms of styles and formatting. This project contains 2 stylesheets :

MainStyles.css - used for tasks, topics and articles

StylesForHomePage.css - used for Home pages.

NOTE | When an element of a stylesheet is updated, these updates will be cascaded to every instance of this style throughout the document stack.

Project Properties

Primary Stylesheet : Mainstyles.css

Skin

This project uses the custom-themed 'Costa' skin which produces a side-navigational menu and customised branding.

Search Results

A search bar is available on every page of the documentation, including the Home pages.

This documentation uses the 'site-only' search engine which produces results found exclusively in this documentation.

Search results highlight the search phrase or anything similar. The colours are ranked in order of search-word priority.

Use the Remove Highlights button to remove the coloured search results

Sample of search results

Images

Images in this documentation were captured from a 4k display directly from GRID 2.0 and provide visual context to the training article. Owing to the width of the GRID pages, all images were reduced in size to 75% of their original size. Where possible, the DPI resolution was maintained.

All images in this documentation uses the left-align format. This can be updated in the MainStyles.css stylesheet if preferred. The style element Text > Align is used to do this.

Tables

Tables generally require their own stylesheet when specific themes are used. A stylesheet called 'Rows' is available in the Resources / TablesStyles folder. Updating this stylesheet will cascade these updates to the entire project documentation where tables are used.

Page Layout

This project uses accepted technical writing techniques which makes use of a page theme for each Task, Topic or Article. This layout is available in the Template.htm page and a sample is used below.

All styles associated with the page layout are formatted in the MainStyles.css stylesheet. The line heights have been calculated such that no spacing is required between items in the page.

Page layout for tasks, topics & articles

Conditional Text

When text is duplicated or appears in the content of other modules, a conditional tag is used to annotate this. This is useful for updates and prevents information from being excluded when information is updated.

Bullets & Numbering

All indented items use the Square bullet markers, shown below.

Indent Line 1
Indent Line 2
Indent Line 3

These styles can be modified locally or in the MainStyles stylesheet.

File-Naming Conventions

Multiple modules are produced in this project. For this reason, file-naming conventions have been observed. For example, all files in the Price Cards module are prefixed with the name of the module, then a description of the article.

Additionally, the use of strict file-naming conventions assist the search engine to locate pages containing specific keywords.

Sample of file-naming conventions for 'Price Cards'

Variables | Annual Automatic Update

Standard Windows operating formats are used to create an automatically updating year for the content. This can be viewed in Project Organizer > Variables > Annual Update. When this formula is inserted into the master page, for example as part of the Copyright (symbol) year, the date will automatically synchronise to the current year. For example :

Refer to the Team Training & Documentation module for assistance with MadCap Flare elements.