The 'Blog' page

News and musings from the Koala team ...


Get 'Konverted'

New conversion service announced;

Database Conversions
Do you ever need to convert a database from one format and structure to another? For example, the contents of an old inefficient MS Access CRM into restructured SQL Server for a proprietary CRM such as 'ACT!' ?

Text Conversions
Or to convert text from multiple files in different structures and file formats, into a valuable single data resource, ready for re-using by your staff and customers in a number of exciting new ways: searchable databases, selected publishing for manuals, training material, online resources and more?

Graphics Stylising
Or to convert legacy drawings, diagrams and illustrations into modern, eye catching graphics which attract and inform the user.

Such conversions have traditionally been tiresome and potentially expensive (even though they save you money in the long term). Well, we've recently decided to do something about it.

We now offer conversions like these as an additional service at very favourable prices. Click here for more information.

 Back to top


Publication Integrity - Part 4

by Robin Shobbrook

Welcome to the final blog in this series on Publication Integrity. This time we're taking a look at publishing processes and publication dissemination in the busy world of technical information management.

Let’s say we have gathered together all the information we need to include in our new publication: text, graphics, tables etc. We have been through review and approval cycles and are ready to make it available to the outside world – or at least to the defined community we want to circulate it to.

Once, it was simply a matter of getting it printed and circulating the paper copies to the users. Not that simple as a matter of fact, but at least we only had one choice. Now we have many choices. Are we going to produce:

This is where structured documentation, XML and DITA can help of course. Because we are keeping our content independent from layout, we can output many different formats and styles, all from the same shared source content.

It means that, at publication time, we can output all the formats we need simultaneously with just a few clicks of a button. It also gives us the opportunity of dynamically inserting document information ...

See the full blog ...

 Back to top


Publication Integrity - Part 3

by Robin Shobbrook

Welcome to the third blog in this series on Publication Integrity. This time we'll highlight some aspects of updating documents which often don't get proper consideration in the busy world of technical information management and publication.

Accuracy, Consistency, Layout and Corporate Standards

Imagine the scenario. You notice an error, or need to change a whole section, in an important technical publication. You want to get it done quickly so all your users/
customers have the correct, up-to-date information. You authorise an editor to make
the change.

But, in today's highly regulated and competitive environment, you also really need to consider the following before you proceed: accuracy, consistency, layout and corporate standards ...

See the full blog ...

 Back to top


Publication Integrity - Part 2

by Robin Shobbrook

Welcome to the second in this short series of blogs on publication integrity in the world of technical information and technical publishing. In this part, we look a little deeper into content management and 'resilience'.

Content Management and Resilience

Ever had a problem finding a file? Take for example, a single Word document:

Well, if it's just the one file, given a little systematic thought and detection, you can usually figure it out (eventually!) so it's not much of a problem.

But structured documentation, with all its undoubted benefits, does bring with it the challenge of managing multiple component files for each document: thus raising issues of content management strategy.

Let's take for example a single 100-page document, engineered to meet the DITA (XML) standards. Whilst ending up as a single document, it will inevitably be made up from many individual component files: DITA maps, topics and images – maybe over 100 files in total! Added to this, many of these files may be shared with (or be referenced by) one or more other documents. So, instead of keeping tabs on just one file, you now need to manage maybe 150 files – and possibly many different versions of each.

To do all this manually, using the Windows file system, is clearly impractical – especially if you also have multiple users of the system. So here is where we need the ubiquitous content management system (CMS). Or more precisely, a Component Content Management System (CCMS), designed to handle chunks of information at a
granular level.

See the full blog ...

 Back to top


Publication Integrity - Part 1

by Robin Shobbrook

In this short series of blogs I’m going to consider the subject of Publication Integrity in the field of technical information and technical publishing. Let’s start off with the issues of document history, provenance and authority.

History and Provenance

OK, so imagine you have produced a well structured, well laid-out, fully informative, unambiguous set of technical documentation: user guides, specifications, maintenance manuals, procedures and training material. You and your team have put in a lot of effort into creating, fine tuning and updating it all.

Now imagine that a regulator wants to audit your documents and asks you to show the provenance of some of the content: -

Or perhaps your quality or safety manager asks the same questions. Worse still, you’re involved in a legal dispute and the accuracy and clarity of your documentation is brought into question.

In highly regulated, safety critical and potentially litigious areas of industry and commerce, these are all increasingly relevant questions being asked. So how do you provide the answers?

See the full blog ...

 Back to top


To be or not to be?

Structured Documentation: Prevarication, Motivation and Persuasion

by Robin Shobbrook

As with many things in life, it’s more comfortable to carry on doing what we have always done. After all, it works doesn’t it? And we know how to do it – there’s no point in having to learn new techniques and changing just for the sake of it?

Trouble is, in technical communications, the world is changing around us. Customer and user requirements change. New rules, regulations and standards become mandatory. Expectations increase. There is a demand
to work faster and smarter. Publishing formats have to cater for reading on mobile devices – instant up-to-date information on demand in easy to assimilate chunks.

We can’t just become dinosaurs - we have to change!

But making it actually happen is the big challenge. We have to convince all the key actors within the organisation that there are real benefits to be accrued through taking a fresh look at our technical communications – how they are structured, how they are created, maintained, managed and distributed. And we have to make a start by determining that there really are benefits in our particular case!

See the full blog ...

 Back to top


Control your English

by Gordon Dennis

The great richness of English that makes it wonderful for authors of literature unfortunately obstructs
precise meaning in technical communication. If your job is maintenance of a piece of safety-critical equipment, miscommunication can be extremely serious. Controlled English is a powerful software solution to address that problem.

There are now over 1,000,000 words recognised in English, according to the Oxford English Dictionary. If English is not your first language, there are all sorts of pitfalls. For example, the word 'CLOSE' can be a verb meaning to shut something (for example, a door); or 'close' can be used as an adjective meaning "near to". Nouns like 'NOTICE' can be misused as verbs ('notice' meaning "to observe"). The word 'JUST' can mean "now", as in "immediate". 'Just' can also mean "only" or it can imply "fair", as in "a just verdict". The word 'MINUTE' can mean "very small" (i.e. related to physical size); or "one sixtieth of an hour" (i.e. related to time).

Using a second language, understanding the main sense of something, but perhaps not every single word, is quite common. For safety critical activities like aircraft maintenance, that isn’t acceptable. Mistakes can have disastrous consequences. Controlled English is based on ASD Simplified Technical English (STE), and it lets you "clean up" your documentation so that such problems are minimised or eliminated. This helps prevent serious accidents and/or costly resulting litigation. There is another benefit; usually the total word count is reduced, sometimes by 30% or more.

A new large-scale example where STE is considered necessary is the A400M Atlas military airlifter for the Royal Malaysian Air Force. Simplified Technical English using the MAXit Checker is used in Spain, Canada, France, the UK and the USA for this program. First deliveries of the Atlas to Malaysia are scheduled for 2016.

Is Controlled English exclusively for people whose first language is not English? Certainly not. If English is your mother tongue, you will probably master up to 40,000 words - about 4% of the OED’s total. Take a previous example, the word "MINUTE", meaning "very small". To be completely unambiguous, we need to know "relative to what?" - i.e. we need a unit of measure to be precise about the meaning of "minute". Even for native English speakers, Controlled English provides reduced ambiguity.

Lastly, if the documentation has also to be produced in other languages, Controlled English provides the best starting point. Controlled English facilitates the use of translation search engines and reduces the manual translation costs required.

If you work in international markets, and documentation is key to your product or service, think of Controlled English. To arrange an online demonstration, contact us now.

 Back to top


"Going Mobile"? "put a print document on a tablet"!

by Gordon Dennis

We can't predict what the user will need to do with the information we provide. One of the biggest limitations of printed manuals is that the user has to work their way through a pre-ordained structure; the manual is written in a linear fashion, whereas the user's requirements are non-linear. They will be entirely context dependent and the context may well be different on each and every useage.

The most important opportunity that mobile technology presents us with is that we can build a non-linear publication relatively easily; but this cannot be done by simply placing a print file onto the mobile device. Doing it that way in fact negates the potential advantage that the mobile device can deliver.

The key aspect of mobile technology we need to take advantage of is visual interaction. By this I mean using the touch screen to its fullest advantage. Using XML-based technologies like SVG means that for example diagrams can be fully interactive. Simply putting up a print file on the mobile device won't allow this.

Mobile devices can also offer significant and in-context outreach. Yes, we can insert hyperlinks into a print document. But allowing us to click on a part in a diagram and linking this to a spares database (internally passing the part number in the process) is not really practicable with a print document. This can however be achieved using a specialised mobile device viewer. Learn how to make full use of mobile devices for technical communication.

Learn how to make full use of mobile devices for technical communication.

 Back to top


The benefits of using a structured documentation methodology

by Gordon Dennis

Why would you adopt a structured approach to authoring technical publications? What's wrong with traditional word processing anyway? Why should we change - we've always done it the old way? We aren't XML gurus!

These are things I often hear so I'm sure they are on a lot of people's minds.

Why would you adopt a structured approach to authoring technical publications?

What's wrong with traditional word processing anyway? If your manuals are large and complex, then you'll know what's wrong: pagination issues, layout issues, and the fact that the whole things becomes too large and difficult to manage.

Why should we change - we've always done it the old way? See the last comment. Plus all the duplication which means the whole process is much more expensive than it should be; and with uncontrolled copy and paste operations being committed everywhere, inconsistencies that can at best be embarrassing (harm to reputation with customers); maybe costly (risk of litigation); and at worst become a flight safety issue (procedures incorrectly documented).

We aren't (and don't want to become) XML gurus! My contention is that with today's software tools ... you don't need to become a guru or anything of the sort. User interfaces are very close to, and just as simple as found in word processors, but generating XML under the covers. your subject matter experts can write XML content without knowing anything about how XML operates.

Read our concise guide to the benefits of the Structured Approach to technical publications.

 Back to top

Is your documentation helping ... or holding you back?

by Gordon Dennis

Very few organisations think of documentation as being an integral part of the products they sell. And yet, documentation is one of the first area through which most users will make contact with your company. And, as we all know, you only get one chance to make a first impression.

Have you ever asked yourself:

Learn how to examine your documentation for competitive advantage in
Who Cares about instruction leaflets?

 Back to top



Koala enhances NATS software

Under its maintenance agreement with National Air Traffic Services (NATS), Koala has frequently delivered enhanced components of the NATS Nucleus suite.

Originally developed by Koala in 2009, the system has been continually updated with additional capabilities by Koala on behalf of NATS over the subsequent years. For example, two new components enhanced visual representation, including integration with Google® Maps. Also, an authoritative AIXM snapshot is now integrated into the Transform product within Nucleus, so that features can be identified by their unique identifying ‘mid’ values earlier in the process and so streamline the processing required to update data in the AIM database.

Learn more in our AIM case study

 Back to top

'Human Factors' Training Goes Mobile

An advanced new method of deploying training material to the aviation industry is being launched by Air Service Training Limited (AST). Masterminded by Koala, it will enable students to download training resources online for use on tablet devices as well as other computers. Once it's downloaded, students will be able to access the material any time they want, even if they are not connected to the internet.

This is one of the first eLearning applications in aviation based on DITA. Single source publishing of eLearning material like this means real savings for the content owner and also ensures that quality is maintained across all the supported devices – once the source is correct, it’s automatically correct everywhere with no additional effort.
Click here for more

 Back to top

Single Source Document Publishing (and Content Re-use) with DITA

by Gordon Dennis

In my last couple of Blogs, I've championed the cause of the Darwin Information Typing Architecture for building technical publications. This time we'll look at DITA's Single sourcing/re-use capabilities.

The core concept of DITA is topic based authoring - the minimalist based concept where large publications are built up from re-usable topics rather than built as a monolithic block. Word wasn't designed to work with topic based authoring, nor for building documents by selecting and reordering content. In contrast, DITA was specifically designed around the concepts of topic-based authoring; minimalist; re-use and re-purposing; and conditional processing.

Minimalist means writing the topic with just enough information (rather like just in time manufacturing) - not too little, not too much.

Expressing this our way is that "the topic title shall describe the topic, the whole topic, and nothing but the topic". For example, we might have a topic named 'Engine fire in flight' and another named 'Engine fire on ground'. Why are these two separate topics? Because the procedures for handling these two different emergencies are different; each therefore stands on its own as a DITA topic.

DITA includes something called a DITA map that lets you gather DITA topics together to form a publication. DITA maps let you specify the topics you want included in a publication. You can also use conditional publishing - for example, some topics published for all versions of a manual, other topics for a version intended for a more technical audience. You can also use a different DITA map for each manual - for example an Operations Manual could have one DITA map and a Training Manual another DITA map. Both DITA maps can share many topics, and also have unique topics of their own. DITA maps actually do much more than this - to find out more ask about one of our structured information MasterClasses.

Having assembled a publication, with DITA you can generate content in multiple formats, like PDF, tri-pane HTML, CHM (Windows help), Eclipse InfoCenter Help, even for a user interface text.

The key point is that you do the job JUST ONCE, not once for each version. And the work of making each version is done automatically. That's using machine time - which is cheap - instead of people time, which isn't.

 Back to top

How did we do all That?

by Gordon Dennis

How did we manage to get out three in depth commercial proposals; one white paper; and some technical assistance material for a partner organization in New Zealand, all in the space of a few days? A collaborative effort involving several team members, all with other things to do.

The answer is that it was all courtesy of single sourcing using XML and DITA. Descriptions of much of what was needed were common between all the documents we released; for example the discussion about DITA topic design principles is not only the same, but needs to be the same for all the people we send it out to.

Our tools of choice to achieve this consist of XMetaL Author, plus Koala's Modulux content management system.

XMetaL is a native XML editor with a word processor-like user interface; anyone can be using it productively in a short space of time. Modulux is a DITA topic repository providing user rights management, formal revision control, archiving and audit trail. It builds controlled publications from collections managed by DITA maps, giving a final result that is traceable, attributable, and audit-able.

Just two low cost products that can help you achieve miracles too!

 Back to top

What's Wrong with using WP or DTP for Technical Publishing?

by Gordon Dennis

The first thing I'm going to highlight is consistent formatting - or rather inconsistent formatting. When I big up this subject, my listeners usually counter by saying "I use my Word processor's templates". And that's a problem. Technical documentation is normally put together by relatively highly paid Subject Matter Experts - in our industry senior Flight Operations people or senior Engineering people; this means that not only are these people costing money; they are denied that time to go out and earn money for the company.

Reality is that, with Word templates, people spend far too much time tweaking what a Word page looks like for each document. This is particularly the case in technical documentation, especially when the content comes from multiple sources. I can't begin to count the number of times I've heard people talking about "pulling in Excel spreadsheets" or an illustration from a CAD system into Word and then spending more time sorting out formatting inconsistencies than they did on the numbers in the spreadsheet in the first place.

This layout inconsistency may be merely annoying because it meddles with a Corporate look (although not many marketing people would say that was just "annoying") but it could be worse. For example there may be data in a running footer. If this gets deleted in the "tweaking" process it could make the document legally inadmissible, or rejected by a regulator. And that's just the sort of thing that happens when "tweaking". Not necessarily deliberately, but mistakes can and do get made.

Another frustration is bulleted and numbered lists. These are cumbersome in Word - for example if you need to mix bulleted and numbered points. And the auto formatting (which has a habit of applying itself just when you don't want it to) can drive you nuts and cause you more work. It depresses me when I hear people say they will spend time correcting this. More time wasted that shouldn't be happening.

DITA is faithfully consistent when it comes to formatting. Transforms available through the DITA Open Toolkit, CSS and XSL-T take away the manual tweaking.

So, why not check out DITA and XML to see some consistent formatting, and see layouts generated automatically.

Remember because it's automatic, you'll be paying for computer time, which is cheap instead of people time which is expensive.

Contact us to find out how you can get consistent formatting and reduced costs.

 Back to top



Data, text and graphics get 'Konverted'
Publication Integrity -
   Part 1,  Part 2,  Part 3,  Part 4
To be or not to be?
Control Your English
"Going Mobile"? "put a print document on a tablet"!
The benefits of using a structured documentation methodology
Is your documentation helping ... or holding you back?
Items from the Blog Archive