Archive for the ‘Author-it v5’ Category

h1

Learning Author-it

May 3, 2011

My good friend and fellow Author-it Certified Consultant, Char James-Tanny, has her new book at the publishers. It will be ready for release and sale at the STC Summit in Sacramento, California in mid-May, 2011.

Her book is called ‘Learning Author-it‘ and it’s a very practical and useful introduction to the fundamentals of this complex, featured-filled and amazing software. How do I know this? Because I had the privilege of editing it!

Front cover of Learning Author-it book

Char and I have collaborated before on Author-it stuff, such as joint conference presentations and introductory training materials, and I’ve previously edited her other Author-it training materials, so I was honored to be asked to edit her book too. An even greater honor was to be asked to write the Foreword.

To round it out, our good friend Sue Heim did the indexing. Those of you who attend the same conferences that we do, know that we all hang out together, so it was great to work together too.

The time zone thing also worked well. Char would send me a revised version at the end of her work day (often midnight or later), which I’d receive during my day. As most of the editing was done over the Easter break, I’d work on it during my day, then send her my edits, which would be waiting in her Inbox when she woke up. So there was hardly any down time when one of us was waiting for the other.

If you use Author-it, or are planning to use Author-it, read this book. Not only are there heaps of step-by-step instructions, Char also goes into the reasons why you do — or don’t do — something in Author-it.

The book is available for pre-order from XMLPress (the publishers): http://xmlpress.net/publications/learning-author-it/. It will also be available at the STC Summit (where Char might even sign your copy for you!), from Barnes & Noble (pre-release), and from Amazon.com after it’s been released.

[Links last checked May 2011]

h1

Using a database to store content

February 15, 2010

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]

h1

Unofficial Author-it wiki

July 14, 2009

Hamish Blunck, a fellow Australian Author-it user, has set up an unofficial Author-it wiki where he and others are documenting Author-it tips and tricks, linking to some good stuff on the Author-it User Group, and generally providing an unofficial supplement to the official Author-it Help and Knowledge Centre.

You can access the wiki here: http://aitwiki.hamishblunck.com/tiki-index.php To post, edit, etc. you’ll need to register.

From Hamish’s original notification:

One of the strengths of the Author-it is the help and support that members of this list provide to each other. But it occurred to me a lot of this useful information is lost and buried in the mountain messages and not captured anywhere. I also thought that it would be useful to have a repository of this great information. I encourage you to add your tips and tricks, your how-to’s, or if you find a great post about Author-it on the web, link to it. Or if you ask a question on the list and you get a useful reply or solution, add it to the wiki.

h1

Author-it: Importing Word 2007 DOCX files

July 7, 2009

Author-it 5.3 (and earlier) only has an option for importing Word 2003 (DOC) files. It appears that you can’t import Word 2007 files as there’s no DOCX option listed for the file type and any DOCX files in your import directory don’t show.

You have two options:

  • Save your Word 2007 DOCX file as a Word 2003 DOC file and import that
  • Use the workaround below to import the DOCX file.

Workaround

  1. Go to the directory where the DOCX file you want to import is stored. Copy the file name and extension (e.g. filename.docx).
  2. Go through the normal steps to import a Word document (Import tab > Word).
  3. When you get to the directory where you have to chose the Word file, you won’t see the DOCX file listed so you can’t select it. Instead, paste the copied file name + extension into the File name field, then click Open.

Your DOCX file should import successfully!

(Thanks to Char James-Tanny who provided this workaround; this workaround is also published on Hamish Blunck’s unofficial Author-it Wiki)

h1

Presentation: Customizing HTML Outputs from Author-it

June 24, 2009

I delivered this presentation at the annual WritersUA Conference in Palm Springs in 2006.

Be aware that Author-it software has been updated several times since 2004 so some of the techniques shown in this presentation, which applied to v4.x, may not be relevant now.

All accompanying handouts are available from the CyberText website.

The focus of this presentation was on:

  • how the various Author-it pieces fit together and what you need to make it all work
  • how to modify the default HTML templates for HTML-based Help and websites
  • how to set up Author-it to produce HTML newsletters
  • how to set up Author-it to produce HTML-based slide presentations

[Links last checked April 2009]

h1

Presentation: Time-saving Techniques Using Author-it

June 17, 2009

I delivered this presentation at the annual WritersUA Conference in Las Vegas in 2005. Be aware that Author-it software has been updated several times since 2005 so some of the techniques shown in this presentation, which applied to v4.x, may not be relevant now.

All accompanying handouts are available from the CyberText website.

The focus of this presentation was on how to:

  • create, assign, manage, and use Author-it variables
  • use system variables to add ‘feedback loops’ for online content
  • create, manage, and use embedded and reusable content
  • use release states to save time for reviewers
  • use release states to create “What’s New” and “What’s Updated” topics

[Links last checked April 2009]

h1

Presentation: Author-it Tips and Tricks

June 10, 2009

This presentation was a collaborative one with the other inaugural Author-it Certified Consultant, Char James-Tanny. We jointly delivered this presentation at the 51st STC Annual Conference in Baltimore in 2004. Be aware that Author-it software has been updated several times since 2004 so some of the techniques shown in this presentation, which applied to v4.x, may not be relevant now.

All accompanying handouts are available from the CyberText website.

[Links last checked April 2009]