Some work colleagues asked my opinion on using Microsoft Access to store documentation for procedures, and on the possibility of displaying that procedural documentation on hand-held devices in the field. Those asking were not technical writers, and had little idea that vendors in the technical writing world had already addressed a lot of their questions with specific tools to do just what they were asking.
Here is my response.
Using a database to store content
Using a database to store content has some big advantages. Assuming it is set up and managed correctly, and that users (procedure writers, content creators, etc.) can find, edit, and extract the content they need for a particular document, it can offer value in being able to ‘single-source’ certain reusable content, and to separate content from formatting.
For example, you might have some common information that’s used across many documents (e.g. a set of PPE [personal protective equipment], or a partial set of start up or shutdown steps). Writing this content once and storing it in a database to be drawn on as needed for a particular document can save an awful lot of time as content doesn’t have to be written or copy/pasted every time. It also allows for consistency and accuracy — by writing the content once and updating just a single piece of content, whenever that content is used later, it will always be the most current version. And it will always be written the same way as it’s the same piece of content.
The other advantage of storing content in a database is that the publishing of that content can be to one or more formats — e.g. Word, PDF, HTML, DITA, XML, etc. This allows for both ‘for print’ and electronic and web delivery options.
However, the downside is that there needs to be some VERY clever ‘smarts’ associated with how the content is put into the database, how it is found and extracted, how the correct template is applied to the content, how the publishing works (and what publishing options are available). Some content management systems (CMSs) and several Help authoring tools (e.g. Author-it), have very good ‘front-end’ graphical user interfaces (GUIs — toolbars, menus, ribbons etc.) that allow writers to just write and for content administrators to look after the management of the content objects, the publishing, and the templates.
The other downside is the learning curve and training that has to be undertaken for some (perhaps all?) of the content creators in learning how to add content, edit content, extract content, publish content etc. that’s stored in the database. Don’t underestimate this learning curve, and don’t underestimate the resistance to not using Word (which is ubiquitous but not necessarily the best tool for the job). Change management is often the most costly part of the introduction of any new process.
Using Microsoft Access to store content
While I’m an advocate for using a database to store large amounts of content, and particularly, large amounts of reusable content, I don’t believe Microsoft Access is the best storage solution. My understanding is that Access has several limitations, notably:
- limited storage capacity
- limited number of concurrent users.
If database storage of content is decided as the way to go, then I would suggest that SQL and/or MySql are considered — both offer virtually unlimited storage capacity and unlimited concurrent users.
One other thing I don’t know about Access — does it store graphics? Some databases do (SQL, for example). Graphic objects (such as Note and Warning icons, pictures/diagrams of parts etc.) are essential for procedures, so storing the graphics in the database, or at least storing the link to the graphics within the database is an essential requirement. I don’t know whether Access has this capacity or not.
Front-end ‘smarts’/GUI to the database
This is the *big* issue and will be the thing that determines whether acceptance and uptake of the database solution works or not. If content creators have to know/learn database commands just to find and extract data, then acceptance of the solution is likely to fail. There need to be some serious ‘smarts’ to the front end that the content creators see so that they can just write similar to how they’d write in Word.
Most open source and off-the-shelf CMSs have some sort of text editing toolbar; other tools, like Author-it, have quite advanced capabilities as far as text editing goes.
The other aspect of text editing in the pursuit of separation of content from format (see below), is the capacity of the tool to enforce styles. One of the issues with Word documents is that they end up becoming a mess because users don’t know how to use/apply styles, or don’t care. It’s very hard to apply a template to get a consistent ‘look and feel’ when the text is manually formatted or everything is ‘Normal‘ style with inline formatting.
Separating content from format
Separating content from format is a good thing. It allows content creators to focus on the writing, not on what the end result will look like — writers can spend between 30 and 70% of their time formatting Word documents, or troubleshooting Word formatting that goes awry.
The other advantage of separating the two, is to allow the different publishing mediums to render the content in a different way — e.g. a procedure published to PDF for paper printing could look quite different to the same procedure published to HTML designed for a web page, or to HTML for a mobile device (see below).
However, it is critical that someone has the rights (and the knowledge) to create the various publishing output templates required. There may be many templates, depending on the degree of difference required for both the publishing medium and the publication type — e.g. procedures may be published to PDF and to HTML and may be designed to look similar; quick reference cards may also be published to these two media, but may be designed to look quite different.
Those in charge of the creation and maintenance of the various templates must not only know how to use the tool that is the front-end to the database, but also must be very conversant with the various output media — e.g. advanced knowledge of Word, good practical understanding of HTML and CSS, with perhaps some knowledge of JavaScript, etc.
Mobile, hand-held, and other small form factor electronic devices
If content is to be delivered to mobile or other small form factor devices, then this needs to be known early so that templates can be designed to suit the small screen.
For example, procedures that are written in a Word table with the instructions on the left side and the associated graphics on the right side, should display well in print and PDF. They may not display as well in HTML, but the display should still be readable.
However, the display on a small device could well be very ugly and almost unusable. Without testing, I can anticipate all sorts of issues:
- Will the table ‘wrap’ to the size of the screen or be a fixed width?
- Will the images or table cells go ‘off the edge’ never to be seen again? Does the user have to scroll horizontally or vertically just to see the image or the rest of the table?
- Will users miss vital information just because they couldn’t see it (this has serious safety and legal implications)?
- Will there be jump links to various sections in a procedure so that the user doesn’t have to go through screen after screen just to get to the bit they need?
- Will touch screen capability be included? (I don’t know if it can — but thought I’d ask the question anyway!)
(Since contributing my thoughts, several meetings have been held at the company to discuss the procedural documentation deliverables with no definite direction yet… [February 2010])
[Links last checked February 2010]
CyberText Newsletter 