The federated Help authoring system

The federated database is a term that has been growing in popularity in recent months. According to Wikipedia:

Through data abstraction, federated database systems can provide a uniform user interface, enabling users and clients to store and retrieve data in multiple noncontiguous databases

Could a similar approach be used in the field of technical authoring – could we have federated Help authoring systems?

There’s a number of situations where a federated Help authoring system might be needed:

  1. A company is selling a system that includes products from other organisations. For example, a telephony solution might include handsets supplied from a third-party manufacturer. This systems integrator is likely to want the handset manuals to use their product name, “look and feel”, contact details and company logo.
  2. Another subsidiary or department is creating documentation in their own Help authoring system, and you need to include some of their content in your user documentation. For example, these could be Knowledge Base articles created by the Support department, or embedded Help written into the application screens by the programmers. They cannot or do not want to use the same authoring system as you, and you don’t have the authority or desire to enforce your system on them.

There are a number of ways a federated Help authoring system can be set up:

  • One is to agree a common data structure. You could require your suppliers to make their user guides accessible in DITA format (instead of, for example, InDesign). You would need to define which text you wanted to be conditional – such as the company name, product name and contact details. In a federated model, their content would stay in their system, but could be integrated with your content when you generate the user documents. This means if they updated the manual, these changes would appear in your system.
  • Another approach is to simply have the content as an embedded object in your authoring system. You would need to get your colleagues to create content where the formatting information was not embedded with the content itself, and again you’d need to agree which text you wanted to be conditional.

The attraction of this approach is it minimises the effort required by the other writing teams, and it provides a solution where you don’t have the ability to establish a single authoring solution.

If you’re doing this today, feel free to share your experience.

Book review: Confluence, Tech Comm, Chocolate

I was sent a review copy of Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication, by  Sarah Maddox. It’s about using wiki technology for developing and publishing technical documentation, using the Confluence platform, the emerging trends in the creation of User Assistance and, in places, chocolate.

Confluence, Tech Comm, Chocolate

The book is aimed at three audiences:

  1. The person who isn’t sure what collaboration tools and wikis are, and is not yet fully convinced these are platforms they should use for producing and publishing technical documentation
  2. Someone who has used Confluence or another similar application, but sees themselves as a beginner
  3. Advanced users of Confluence.

The author manages to pull it off  - all three groups will find the book interesting and useful.

For the skeptics, Sarah raises and answers a great question:

Isn’t a wiki just a puddle of chaos?

The problem with the word “wiki” is everyone thinks of Wikipedia, with its complicated authoring environment and occasional errors. Sarah explains not all wikis are like Wikipedia, and how Atlassian, the makers of Confluence, struggles to describe the software (it currently says it “provides collaboration and wiki tools”). In fact, Confluence is a tool that can publish EPUB ebooks, PDFs, Word documents, HTML, DocBook files and, probably quite soon, DITA files. It has a rich text editor that looks like Word. It’s a wiki that doesn’t look like a wiki.

The book itself was written in Confluence. Comprising 477 pages, there’s a lot of “meat” in this book. We’d consider ourselves as knowing a lot about Confluence, having used it to build solutions for a number of clients, but there were many useful nuggets of new information.

Enthusiasm oozes through almost every page. That’s partly because Confluence is one of those tools that causes clients to get excited. They very quickly realise the potential outside of the original project. It’s also partly because the author is passionate about the subject.

Examples are built around a hero (heroine, actually) called Ganache, and this approach works well.

The book also looks at new trends in User Assistance – where technical documentation is going and how it will be created. A Cherryleaf article is mentioned in passing. It looks at working in an Agile software development environment, and how a collaborative authoring environment can help reduce the authoring bottleneck Agile can produce.

Sarah also highlights the weaknesses of authoring in this environment. There are issues around round tripping (and whether it’s needed or not), in particular.

Technical Writers will also have questions about translation and localisation of content, which is touched on only briefly. Publishing to .CHM files isn’t covered. However, there is a wiki that complements the book, so readers have the opportunity to raise these questions with the author (and discuss them with other readers) there.

If you’re interested in collaborative authoring, wikis, Confluence, chocolate, working in an Agile environment or where technical documentation is going, then it’s worth getting this book.

Technical writing in the Cloud

One of the most popular developments in computing in recent years has been the emergence of cloud-based computing and Software as a Service (SaaS). Examples of cloud-based computing include Google’s GMail: Instead of an application being installed locally on a user’s computer, it runs on a remote server, accessed via the user’s Web browser.

So is technical writing likely to move to the Cloud? Let’s look at the different approaches.

Why would you want to write using a cloud-based application?

There are a number of reasons why a Technical Author might want to use a cloud-based application. The first reason is cost. Instead of purchasing an application, cloud-based applications are typically offered on a monthly fee basis. If you’re looking to move to a DITA authoring environment, this spreading of costs could prove an attractive alternative to the upfront costs associated with buying a DITA solution.

There are other reasons, why you might also consider moving to a cloud-based solution:

  • If you have staff, a technical writing partner (such as Cherryleaf) or contractors working remotely, cloud computing means you can quickly and easily add them into your authoring environment.
  • If you want to work in a collaborative authoring environment, cloud-based applications typically enable you to do that.
  • If you use a third party company (such as Cherryleaf), you have the opportunity, at a later date, to log into the system and make any minor updates (following updated releases of your product) yourself.

Check in/out

You don’t necessarily need to move to a cloud-based environment, if you want to have remote workers and/or collaborative authoring. The most popular authoring tools, such as RoboHelp, FrameMaker and Flare, use a check in/out model instead of a cloud-based approach. Writers can “check out” a topic from a project and work on it remotely. They can then “check in” the completed topic back into the project, via email or SharePoint.

Your authors will all need to have the Help Authoring Tool on their computers, and you cannot watch them as they write, but it’s worth considering.

SaaS

If you’re looking for a SaaS authoring tool, then there are a number to consider:

  • DITA-based authoring applications and services, such as Doczone, DITAweb and Stilo Migrate
  • Help Authoring Tools, such as HelpConsole and Author-it Live
  • Wiki-based technical authoring applications, such as Mindtouch Cloud and Atlassian OnDemand
  • Word processors, such as Google Docs

You’re usually unable to add any additional plugins, which you’d be able to do if the software was installed on your computers or servers.

You may also need to consider where your data is actually being stored. Data privacy rules differ in the USA and the European Union –  the USA’s Patriot Act, for example.

Your own private cloud (VPN)

Some organisations simply add remote workers to their existing network. The organisation has its own private cloud, a Virtual Private Network (VPN). Typically, it’s up to the IT department as to whether a remote user will be given access to a system. You may need to acquire licences, and you may need to wait for IT to set this all up for you.

An alternative approach is to create a private cloud for your own department. You can create a server in the Cloud, using Amazon’s EC2 service, or using alternatives from companies such as RackSpace or Microsoft (Azure). On this server, you could install for example, a customised version of the Authoring application (containing all the plugins and macros you require), and provide remote workers with a web address, user name and password for them to log in. With VPN server prices starting at $20/month, it’s an affordable option.

If you decide to do this “under the radar” (i.e. don’t tell the IT department you’re setting up your own VPN), you need to make sure you’re conforming to your organisation’s IT security policy. Otherwise, you could be in trouble.

Are you writing in the Cloud?

The reasons for using cloud-based applications seem to be as valid in the Technical Publications department as in other departments. So it’s likely we’ll see a growth in the uptake of this type of service.

  • Are you writing in the Cloud? How have you tackled this problem?
  • Is writing in the Cloud a good idea?

We welcome your comments.

Our client’s fire risk assessment report generator goes live this week

In the UK, every building, apart from private single dwellings, needs to be assessed for fire risk every three years. To do this, a fire risk assessor will assess the building and write a report on their findings and recommendations. For offices, these reports can be 30 pages long, and it can take an assessor a full day to complete the report.

We’ve been working with a fire risk assessment firm to create a system for them that generates these reports in less time and in a more consistent way. Like many organisations, they’ve been using Microsoft Word to write the reports, and this can lead to a wide variation in the way the reports are presented.

Cherryleaf has been developing a report generator for them that significantly reduces the time needed to produce their reports – they believe they can reduce the time needed from a day to an hour – and, this week, they’ve started to print out the assessments they’ve been writing.

So what did we create for them?

There were a number of potential software applications we could have used (for example, Author-it, Mindtouch and Confluence), but the best fit for this client was Confluence. Within this application, we created a master report ‘boilerplate’ that contained all the key information that should go into a fire risk assessment. This master boilerplate ensures there are no omissions in each report.

On the individual pages within the report, there are numerous drop-down sentences and blank text boxes for the assessors to choose. There are also ‘variables’, for chunks of information that need to appear in more than one place in the report – they are embedded in appropriate paragraphs. If you change the information contained in the variable, then this change is implemented at the appropriate places in the document.

The project has produced a number of challenges. For the client, they have been looking hard at the content that goes into an assessment report – and how to create a single report that satisfies the many different standards for fire risk assessments. For us, we’ve had to create a system that works for people who might not be very technically literate. For example, people who have never uploaded an image into a document before. We’ve also had to create something that’s very flexible – suitable for assessments of small buildings such as bandstands, bus shelters and suchlike, to big buildings such as tower blocks.

The proof of the pudding is in the eating, as they say, and we’ll soon be able to see how much time the client will save. The signs are looking good, and there’s likely to be further enhancements and developments to their system in the future.

At a rough estimate, there are 10 million buildings in the UK that need to be assessed for fire risk each year. If our system reduces, at a conservative estimate, the time needed to produce each report by 4 hours, then there’s the potential for it to save 40 million hours of writing time per year.

Review of “WIKI: Grow your own for fun and profit”

XML Press kindly sent me a reviewer’s copy of Alan J. Porter’s book “WIKI: Grow your own for fun and profit”. I interviewed Alan earlier in the year (which you can see on the Cherryleaf YouTube Channel), so it was good to see the book that he was mentioning in the interview.

It’s important not to think that wikis only = Wikipedia. You could argue that applications such as Confluence and Mindtouch 2010 are wikis as well – wikis enhanced with powerful tools for software user documentation, but wikis, nonetheless.

As Scott Abel says in the introduction, most organisations have yet to manage the art of managing content. They make two common mistakes: (1) they see content as either documents or structured data, and (2) they see it as purely a software problem.

Wikis offer technical communicators a handy route into an organisations for them to tackle poor content. That’s because wiki software is generally very cheap and the techies like them. There are still issues around “round tripping” (getting content in and out, and back in again) and link management, but these are not insurmountable.

Alan, I’m pleased to say, has not been seduced by the software, but has set the use of a wiki within a very usable framework. He’s spot on when it comes to the benefits a wiki can offer and the implementation approach to take.

Tackling the challenge of writing sales proposals and RFQs

Standards and processes permeate nearly every area of business today. They enable management to control, direct and delegate, giving people the ability to focus attention on the more difficult issues the business faces. Processes drives predictability, consistency and efficiency.

Despite all these benefits, sales departments have been much slower to move down this path. Sales people usually baulk at the idea of processes, complaining that “form-filling gets in the way of actual selling”.

Yet, according to Dario Priolo and Bethany Schultz, from sales training company Miller Heiman,

Our research clearly shows that “Winning Sales Organizations” take a much more scientific approach to selling and sales management than others. While there will always be a certain art to selling, it’s an increasingly sophisticated business world…How much better would a CEO sleep at night if he knew his sales force had a consistent, professional approach to interacting with customers! An improvement in these factors helps drive revenue predictability, reduces cost of sales and increases sales force productivity—all critical business objectives.

Miller Heiman argues that a sales process can help sales people “sell more and sell faster”.

Any successful initiative must include tools to streamline the process and remove any barriers to change. In this context, it makes sense to streamline one of the most time consuming aspects of selling – responding to Request for Quotation and other forms of sales proposals.

As we mentioned in our post “Building intelligence into business documents“, it’s now possible to create a system that can build the bulk of the document in a matter of minutes, leaving the writer with the task of customising the information to suit the requirements of each particular situation. These systems can even include training videos and text to guide a writer through the process of developing a new document, as well as enforce consistency and standards.

In the near future, we’ll be providing details on some the solutions available to organisations that want to improve the process of writing sales proposals and RFQs.

What does a Help Authoring Tool give you over Drupal?

Comparing Help Authoring Tools (HATs) with Drupal is like comparing apples with oranges.

HATs are used by Technical Authors to create content in various formats for end users to read. Drupal is open-source software that is used to create websites for users such that they can contribute to the content (for example: blogs, personal or corporate websites, e-commerce sites and intranets).

That said, if you are a HAT user and then have to work in Drupal, it is useful to be forewarned of the main differences. The top 3 things that a HAT user will miss when starting to use Drupal:

1. The most frustrating thing about using Drupal, having come from a HAT background, is having no summary list of pages (topics) available in a different frame.

As an Administrator in Drupal, you can view a list of pages, but you can only edit the properties of one page at a time. There is no multiple-selecting and no drag-and-dropping. So topic management can be very labourious.

2. Out of the box, there is no way of managing links. So, for example:

  • If you delete a page then all links pointing to it will break, and there are no messages to warn you.
  • When creating a link in a page you have to know the path and name of the destination page – there are no helpful lists of available pages.

There are modules you can install, which can help. The “Links” module is the most complete on paper but, in Drupal 6, it can cause a programming error (i.e. not an error in the way I installed it).

3. Out of the box there is no WYSIWYG editor. For the majority of HAT users this is a must. You can only write your content in full/filtered html.

I highly recommend installing the “Wysiwyg” module. This module makes it much easier to install WYSIWYG editors. Some of these are less successful than others. If you are interested in keeping your underling code clean (i.e. free from unnecessary <span> tags created by inline styling), I recommend the “TinyMCE” editor.

Video of a simple report writing solution

Here’s a video of a proof of concept prototype we’re putting together for a client. The system automates the creation of field reports. It creates a skeleton document, with key content populated. Many pages contain guidance on what to write.It is probably the lowest cost content management system we’ve put together.

If you can see the video below (there’s a problem viewing it on the main page of the blog) you can view it here.

This text will be replaced