bookmark_borderHacking Author-it Webhelp

Finding the right solution for a problem isn’t always easy but sometimes, if you are very lucky, the solution will fall straight into your lap. Such was the case with our switch to Author-it even though we didn’t fully realise it at the time.

I’ve covered our reasons for switching from FrameMaker to Author-it elsewhere, and once we had converted our content we started to look at how we could get the most from the other output formats available. We already had ideas on how we could use the provided HTML based publishing formats to provide a better solution to the problem of finding information, and we were planning on generate HTML versions of the entire documentation set to be hosted, and searchable, on our community website.

It was right about then that Author-it announced their new ‘Webhelp’ format which would include a (very) quick search in a nice modern looking format. Given that one issue we were addressing was how hard it is to search across multiple PDFs (which presumes the poor reader knows which PDF they should start with) it looked like an excellent solution.

And it is.

We now host a specific build of all of our content within our developer community (which is password protected I’m afraid so you’ll just have to trust me), which allows the developers, partners and customers, to search across everything we have. However we have had to customise the output a little to meet our needs, and this is where the hacking starts.
Continue reading “Hacking Author-it Webhelp”

bookmark_borderAuthor-it Web Help Configuration Wizard

For version 5.3, Author-it released new web help templates and having played with them a bit I have to say I like them. However I was struggling to see how to enable some of the options that you can see in the example Author-it provide, so off into the HTML and CSS files I headed to see if I could see anything useful in there.

And there is, several of the options are commented out in the HTML code and with a little bit of poking and prodding I got some of them to work. Pretty straightforward, if you know HTML and CSS that is.

But what if you don’t?

Well the good news is that the ever productive Hamish Blunck has created an Author-it Web Help Configuration Wizard which, in a few simple steps, will produce you a custom Web Help template. It really is very simple and works like a charm, it also uncovered a few options I hadn’t spotted in the code.

Thanks to Hamish for providing this to the Author-it community (he also hosts a search engine that polls the old Yahoo Group). Great stuff this, go and give it a shot.

bookmark_borderLessons learned

It’s all go at McLean Mansions but that’s nothing new for the first week in May with my sister celebrating her birthday on the 5th and my sister-in-law celebrating hers on the 7th. Of course that means presents and nice meals in restaurants, so we were out for dinner on Monday evening, and we’re back out tonight. Twice in one week! I know, I know, such a heady life I lead.

It’s not all fun and games though, I’ve spent the rest of my evenings either watching football, working on a client website, and royally screwing up my Windows PC (thank heavens I have a Macbook as well). Add in a fairly mental week at work and a rapidly filling list of things to do and I’ll admit that I’ve not really been fully concentrating on some things.

In other words I’ve fucked up a couple of things. But hey, a wise man once said you “learn by your mistakes”, although this stupid man is wondering how many more mistakes I need to make before being granted “wise” status.

However, in the spirit of sharing, here are a couple of the lessons learned.

* Geek warning active *
Continue reading “Lessons learned”

bookmark_borderDesigning websites

As well as my full-time job, in my spare time I also design and build websites. It’s something which fits well with my skillset as a technical communicator, and allows me an insight into the world of development as well and has mirrored my career every step of the way.

The first company I worked for sent me on a training course to learn how to create web pages and, since then (13 years ago), I’ve continued to follow the trends and techniques involved. I’ve been through using tables for layout, to the introduction of frames, the launch of Internet Explorer and the first release of CSS.

The parallels between the theories of technical communications and those of web design are very similar, the key aim is to keep the audience in mind at all times. The way you structure and present the information is also important, as is a sense of usability of the content itself.

I’ve been lucky enough to have a fairly constant stream of web design work, largely by word of mouth, and have just finished chatting with another potential client. Part of my approach is to ask to have a questionnaire filled in, largely to help me understand the requirements for the website, as well as to have something to focus the initial conversations around.

Two of those questions are:

  1. Who will be using your website? What is the intended/current audience?
  2. Does your current website meet the needs of your audience? If not, why not?

Which, as I’m sure many of you will already have realised, is exactly the kind of questions we, as technical communicators, should be asking ourselves on a regular basis.

bookmark_borderUA Conference Notes – Day 2

Notes and thoughts from Day 2 of the User Assistance Conference

Session 1 – Juliette Fleming – XML Tagging and Search Facets
An early start for an interesting session in which Juliette outlined how Oracle have introduced search Facets to their online help system. Essentially a facet is a tagged chunk of information or help topic, and their help system has been coded to make the most of these by using the tags to decide in which context the help topic should be used.

This allows their help system to display information, for example, for a given product version, language, product and topic type when the user clicks to get help from the application. The facets are also used to present, essentially, pre-populated searches as a starting point (or Keystone Concept, perhaps) for the context-sensitive help. A smart idea.

Session 2 – Tony Self – Implementing Collaborative Authoring with Wikis
I didn’t attend this session but heard it was a good introduction to the topic for beginners. Having presented on this topic myself I figured it was safe to take some time out.

Session 3 – Rachel Potts and Brian Harris – Delivering Help in a Support Portal
An entertaining presentation on a topic that matches some of my thoughts of where my team and I should be heading. The core problem that Red Gate had was to tie together the myriad of information sources into a cohesive whole as they figured that their users didn’t care where or how they got the information they needed, even though Red Gate offered many distinct to try and guide them to a particular type of information.

With a little effort they came up with a solution which included restyling some of the existing information, and taking a new direction for the online help, recognising that most of their users would look for Support rather than Help (acknowledging that most people don’t like to admit they need ‘help’!). Shifting to Author-it for their technical writing team, they post-process the output to provide better metadata which enables the search engine and supporting presentation framework components to offer the best information at the best time.

As we are moving to Author-it it was very interesting but I was a little disappointed to find out (when chatting to Rachel and Brian later on) that they are ditching Author-it because, when creating new versions of topics, you lose the associated metadata. I’m hoping that’s just a bug that has yet to be fixed and will be checking that with Author-it very soon.

Session 3 – Dave Gash – Introduction to XSL Transforms
Following on from his presentation the day before, Dave suggested that this would be an easy to follow session on a fairly simple topic (even though it can end up being very complex to pull together).

However, having dabbled with XSLT myself I decided to sit this one out and spent some time chatting to some of the vendors.

Session 4 – Leisa Reichelt – Practical User Research
Having been an avid reader of, where Leisa blogs on User Experience topics, and as it wasn’t directly a technical writing focussed presentation, I was looking forward to this presentation. Leisa’s style and delivery kept it interesting and informative, and seemed to be very well received.

Taking the role as a user advocate is a common one for a technical writer, and a lot of what Leisa was discussing was simply taking that a step further. She offered some suggestions on how to capture better user information as well as offering some simple reasoning that shows you can do useful research with a small set of subjects, and a simple model that shows that, without all the correct design processes in place “changing buttons on a user interface is like shuffling chairs on the titanic”.

As I’ve mentioned here on this blog, I’m a big fan of technical writers pushing (or encroaching?) into other areas. For many smaller companies without the budget to hire a dedicated usability professional it’s good to know that even a small effort in this area can make a difference, and that effort will mean a better understanding of your audience which is always a good thing.

Session 5 – Matthew Ellison – Creating Table Styles in CSS
Again, another session I skipped largely because I’m quite comfortable styling with CSS and a quick google suggests similar information is widely available online.

Session 6 – Prof. Geoffrey K Pullum – Far from the Madding Gerund
I have to admit that it was with a wary head that I took my seat for the closing session of the conference. I’ll happily admit (and lord knows there is plenty of proof right here in this blog) that whilst my writing is acceptable the finer points of grammar are occasionally ignored, so the thought of listening to a grammarian waffle on about deontic modality or ditransitive verbs didn’t exactly thrill me.

So it was with some humility and shame that I apologies to Professor Pullum as his talk was fascinating, funny and hugely enjoyable. Seating his advice in examples, and several quotes from The Importance of Being Earnest, he assured as all that our writing was perfectly acceptable and that we should ignore people who seek to enforce arcane and just plain wrong grammar rules. Split your infinitives if you must, dangling your modifiers and feel free to end that sentence with a preposition if you feel the sentence warrants it.

Ultimately, Prof. Pullum assured us, we are all professionals and the way we write is accurate for the audience. That and the fact that a lot of grammatical advice is complete nonsense.

If you get the chance to hear him speak, do so. Even if only to hear his range of accents, all of which are executed so well I have to wonder if he spends some time practising them.

bookmark_borderUA Conference Notes – Day 1

Notes and thoughts from Day 1 of the User Assistance Conference

Session 1 – Tony Self – Emerging Help Delivery Technologies
It’s been quite a while since I heard Tony speak but as ever he provided an entertaining, if somewhat limited, presentation. Covering the various types of help viewing technologies he nicely summarised some of the available choices including the features to look out for, including the ability to wrap up an online help system in its own application (using technology like Adobe AIR). It was interesting to hear some Web 2.0 features making their way into online help technologies, including voting and commenting facilities which would give you direct feedback from the people using your help system.

Session 2 – Joe Welinske – Write Mote, Write Less
Embracing the Value of Crafted Words and Images
Another regular speaker and Joe was certainly fired up, challenging us all from the outset of his presentation to consider how we work in far more detail than we currently do. First up he suggests that we should be writing fewer words whilst making sure those words are correct and so lessen the impact on the reader, providing just the information they need and nothing more.

And then he hit on something that I’ve previously mentioned here (although Joe nailed it much better than I did), namely allocating writing resource to the highest priority pieces of documentation work, rather than the traditional approach of documenting everything. It’s a simple approach that, when combined with better writing, leads the craft of technical communications to provide much higher value to the business which is good news for all of us.

Session 3 – Sonia Fuga – DITA & WordPress Solution for Flexible User Assistance
A showcase style presentation of a stunningly simple concept. With a little bit of coding work (building a DITA importer to get XML content into the WordPress database), the team at Northgate offer a web-based help system which allows users to add their own notes and to vote for useful information, and which is can receive updates with new content with each release.

How? By using WordPress features. Notes are left as comments, votes are left using a WordPress plugin, and the updateable content is controlled by only allowing the customer (who has access to the WordPress admin screen) to create Pages, leaving the Posts controlled by Northgate. I use WordPress for this website, and spoke to Sonia in the evening to confirm some of the finer details. It’s a very clever use of WordPress, and I hope Northgate release their DITA importer to the open source community!

Session 4 – Question and Rants
A short session with four speakers each giving a two minute ‘rant’ and then taking questions. Nothing particularly noteworthy came of this but it’s a good addition to the usual style of presentations and made for a little bit of light relief.

Session 5 – Dave Gash – True Separation of Content, Format, Structure and Behaviour
Another familiar name, Dave is always entertaining and a very dynamic speaker and in this session he even managed to make the somewhat mundane topics of HTML, CSS, and JavaScript interesting!

Outlining some basic principles he showed how you could take an HTML file, full of embedded behaviours (javascript), style rules (CSS), and content and strip out all four parts into a more manageable set of files. This way, holding the style and behaviours in referenced files, you can make changes to either and have them ‘ripple’ through all of your deliverable.

Admittedly this was all done by hand but the basic principles are something that you should be following if you have that kind of output.

Session 6 – Matthew Ellison – User-centred Design of Context-sensitive Help
Interesting presentation by Matthew which started a little slowly, covering the history of context-sensitive help before taking us onto the idea of task support clusters. Originally presented by Michael Hughes at the WritersUA conference, the premise is to offer the user a smarter landing page, referred to as Keystone Concept topics here.

The key to a successful Keystone Concept topic is not to limit what is presented, and to consider that it should be different depending on the context from which it was launched, with the ultimate aim of getting the user back on task as quickly as possible. This includes any form of tips and hints, and crucially suggests NOT to include the obvious stuff (don’t answer questions that users will never have!). This mirrors part of the theme from Joe’s talk early in the day, and certainly seems to be a sensible goal given the business (time and resource) pressures we are all under.

After that, I had a few beers and a chat with some other delegates, and as ever it was great to hear that most of us have similar issues, problems and solutions.

I’ll post my notes from Day 2 of the conference tomorrow.