Foul Writer’s World

So I have been busy lately. Hence the lack of posts.

But I thought I would write a short post on a project I am currently working on. It is the deployment of an online multi-lingual help system. The company I work for, Questionmark, are moving towards a Software As A Service methodology. We have several applications out, or in the pipeline, that are designed to be multi-lingual. Questionmark Live, is a perfect example. It allows Subject Matter Experts to easily create questions using a web based interface that can then be uploaded to Questionmark Perception for delivery to students in an exam or assessment.

The current help system employed by Questionmark Live is basic, so I have been looking at ways we could improve this. Essentially I needed a system that could be:

• Used to create help pages
• Able to display images
• Translatable
• Language aware
• Able to provide direct links to pages in an easily identifiable manner

I checked all our existing systems and tools (Madcap Flare, RoboHelp, WikiSpaces, Contribute) but none really did what I needed them to do. I then started checking out other specific Help and Knowledge Base system and I came to the conclusion that they were either really good at organising and displaying information or being multi-lingual aware, but finding a system that could do both really well was impossible.

I decided to start looking outside the box and came across Joomla!. Joomla! is an open source Content Management System, in the same vain as Drupal. However, Joomla on its own isn’t language aware but there a are a multitude of add-ons and extensions that make pretty much anything possible.

My current line of thought for the new help system includes a deployment of Joomla!, with an extension called Joom!Fish. Joom!Fish provides Joomla with a whole translation workflow and makes the software language aware. Also the way that Joomla indexes pages makes it easy for our developers to call specific pages stored on the Joomla system in the language needed quickly and easily.

Each piece of content stored in Joomla is tagged with an ID. Any translations of the content is stored with the same ID so translations are actually part of the same piece of content rather than a seperate piece of content written in a different language. Perfect!

For example to call the help I would need to pass something similar to the following URL (simplified for the sake of this blog post):

index.php?contentid=38Lang=en

If I wanted to call a different page the URL would simply change to:

index.php?contentid=41Lang=en

If I then wanted to present a translated version of the above page I would just need to change the identified Lang parameter, like so:

index.php?contentid=41Lang=es <- To display a Spanish translation of the page

Now this is all pretty easy for our developers to arrange. Each Help button would be associated with a contentid and depending on the language version of the software the user was using the Lang parameter would also be passed to open the appropriate page in the required language. The Joomla and Joom!Fish combination is also clever enough to understand that if a translation of the selected page isn’t available it will show the predetermined base (original) language, which in most cases will actually be English. It can also be configured to work with language cultures like en-US and en-UK.

Another really cool thing that I like about the Joomla system is that I can change the look and feel of the page being called by simply modifying the URL slightly. For example calling the following URL would open the page with the full template and menu system:

index.php?contentid=38Lang=en

But calling the following URL would open the content without any distractions, no template, headers or menu, and display just the article:

index2.php?contentid=38Lang=en

This makes it perfect to open help pages directly from the application, while still giving me the control to allow users to open the help as a help centre with full navigation and searching capabilities. I’m hoping to finish off my proposal for the system in the next few days and get buy-in from various stake holders. So far all the developers I have shown it to love the solution. It makes life easier for them and everyone has agreed that it will make the content more meaningful, relevant and easier to maintain.

I’ll keep you all posted as the project progresses. If anyone else has any thoughts or comments feel free to let me know in the comments section.

Update

I thought I’d include some links to a demo system I have setup.

Here is a link to a sample help page:

www.foulwritersworld.net/joomla/index.php?option=com_content&view=article&id=46&&lang=en

The same page in Spanish:

www.foulwritersworld.net/joomla/index.php?option=com_content&view=article&id=46&&lang=es

With the menu and navigation turned off:

www.foulwritersworld.net/joomla/index2.php?option=com_content&view=article&id=46&&lang=en

It seems Adobe have really hit a chord with the new help system included in CS4. Unfortunately, it doesn’t seem to be the right chord. Richard Galvan (Product Manager for Flash), has included the following post including problems Adobe is working on fixing for Flash CS4. It seems the help system is the centre of a lot of user frustration:

Next topic: Flash Help.

We have received a lot of feedback regarding the changes made to Help. These changes resulted from an internal initiative to make Flash Help consistent with the rest of the Adobe Creative Suite products. These changes also allow the group responsible for developing Help documentation to produce better and more current content. The Help team also wanted to tie in community-based resources and the ability to search, which means that search now returns help results  not only from Adobe, but from other relevant sources on the web.

We are aware that there are severe workflow issues with the current solution –most of which Adobe is working on.  Some of the concerns we have heard are:

• it’s available only when you are online.

• Help now opens in a browser and not in the IDE.

• it opens a different browser window every time you hit F1.

The Help team has assured us that they are working on these issues and on improving the Help experience for the Flash user’s needs.

Please let us know what other issue you encounter with Help. Additionally, if you have any feedback on improving Help to make help better, we are all ears.

If you refer to some of the comments on the post. It seems people really don’t like the new all in one integrated solution that Adobe has implemented. I use Flash CS4 a lot and I must admit that I do find the help frustrating, but to be fair it is not only Flash that has this problem it is most of the CS4 range. As the help has been integrated across the whole platform and is hosted on a centralized server.

This leaves a number of problems some of which have already been brought up by other users:

• Can’t access the help when not on-line (I work a lot on the road while travelling on Trains or in Planes so it can sometimes be frustrating)
• Help no longer feels like part of the application (It opens in a browser window)
• Searched results often cause information overload. The search results obviously go back to an indexing server that automatically searches all the help across the range of applications and provides all these results to the user (Why would I be interested in similar information from other applications in the range. I want help with Flash, plain and simple)

However, the new system does provide the opportunity for the writers to update the system and keep the information up to date easily. Also, this system does reduce the footprint of the applications and for a product range the size of the CS4 Master Collection it really does make a difference on hard drive space..

Thankfully all the problems people seem to have with help seem fixable. I hope the guys at Adobe can improve the help system.

Why still produce manuals and user guides? This is a question I’m beginning to ask myself more and more. People I have spoken to all freely admit to never reading the manual. I myself, rarely read through a manual. So why do I bother? The truth is, I bother because of the 1 person in every 10, ok a 100, which emails back or leaves a comment thanking me for the documentation I produced because it got them out of a sticky situation or improved their own performance. These are the people I still write for, but they are a dying breed.

Granted, I still see the importance for producing written material. Particularly for Knowledge Bases and Troubleshooting. But I find myself increasingly more interested in the technologies behind technical communication rather than the writing itself. I like the idea of new media supplementing the written documents, the use of wikis to give the users a voice, blogs to keep the world informed. Podcasts or Screencasts to guide new users through the features.

I am particularly interested in interactive manuals, because I believe people learn and remember better when they get stuck in. I’m busy developing a new framework for the organization where I work, trying to fit interactive manuals in to a formal structure that will allow for greater reuse. In previous projects where I have attempted to create interactive manuals they have only been partially successful because of time to market.I am hoping with this new framework I can create completely reusable content that will allow me to produce a greater range of interactive manuals, while reducing the time to market for each.

My main tools for doing this are Adobe Captivate and Flash. I also have Mimic 1 but I am not a fan of the MadCap application, although that may change with the release of Mimic 2.

I intend to create “movie clips” that are independent of one another. Which can then, using something similar to DITA’s mapping practices, be used to create a TOC that will link the required movie clips together. What I’m hoping is that to and end user it will seem like one complete movie, full of interactive and learning elements that they will enjoy using and find useful.

At the end of the day I am hoping to come up with something similar to what Microsoft have done with the online training they have produced for Office 2007. To see an example check out the link below:

Microsoft Interactive Guides for Office 2007

I’ll let you know how I progress.

Has anyone got any tips, advice or any other examples?

Work has been a nightmare recently, hence why the updates have been scarce as of late.

I am currently migrating our existing help documentation into Flare. This would normally be an easy task, except that the help documentation I’m migrating was written in HTML that is so badly malformed that I’m surprised a web browser can even show the pages. The help was also generated a few versions ago, and it is easy to see it was written by a developer rather than a technical writer as it is difficult to read and task/ procedures lists are often nested up to four times. The text content also seems to have been placed in a table to apply some sort of layout design. So importing this content to Flare is pointless. Flare usually does a good job of converting what it can, but with these help files it just falls over flat. Because of this I have resulted to saving what I can from the existing help by copying and pasting into Flare what I can and then rewriting what I deem as unfit.

I found an interesting post by Kathy Lawrence that I wish whoever wrote the original help documentation had read through.

Technical Writing in Ten Easy Steps