Technical Communication UK
22nd-24th September 2009

http://www.technicalcommunicationuk.com

Technical Communication UK is the new annual conference that aims to meet the needs of technical communicators, their managers and clients, from every corner of the industry.

The conference is hosted by the ISTC, and run in partnership with X-pubs.

Technical Communication UK runs on 23rd and 24th September 2009, with pre-conference workshops on 22nd September. It will deliver more than 30 sessions over the three days, with presentations, workshops, case studies, and hands-on product demonstrations from experts in their field.

Let me know if you are coming along, as I’d hate to be sitting in the bar on my own on the Wednesday evening!

I’m currently pushing a business case to allow me to hire a new member for our team. The premise is that, particularly with our product set, there will always be areas of technical content that need writing but that with an additional member we can start to create other forms of content.

Which begs the question, what other forms of content can we create?

One thing I would like to get my team more involved with, both to give them a wider view of the product and to help the rest of the R&D team better understand why we build what we build, is in the creation of our Business Requirement Documents (BRDs). These documents drive the product features, setting out the requirements for the new features that we want to add for the next release cycle.

Early on in my career I remember reading (somewhere) that the technical writing team are user adovocates and that we are “the interface to the interface”. With that in mind, we need to understand both why a feature is in the product and how we expect it to be used (or at the very least, how we would like people to use it). By getting involved earlier in the product lifecycle, helping to understand and articulate the business requirements at the start of a release, we can be better placed to act in the best interests of the customer.

Being part of the team that collates and creates the BRDs will place us bang in the middle at the start of a stream of work and, by nature, we are also there at the very end, checking our documentation as the final stages of the release tweak and refine the functionality. My hope is that this end to end view of the product will help both the technical writers, and the development teams in which they are embedded.

Are you involved with early development documentation? If so I’d love to hear your thoughts on this.

I’ve mentioned before that I’ll be attending, and presenting at, the Technical Communication Conference this year, but as the programme is now full I’ve been trying to pick my way through which sessions to attend. I think I’ve got it sussed.

Wednesday

Kicking off with the keynote from Peter Anghelides (who recently re-tweeted me on Twitter!).

Session 1 – Matthew Ellison – Pattern language for information architecture
As we delve into providing more of our information online, understanding how best to structure the information is key.

Session 2 – Kim Schrantz-Berquist – If you can write an article, you can write anything!
I have a long term goal to get my team to a position to allow them to write different kinds of information. Articles for our developer community are a good path towards that.

Session 3 – Linda Urban – Paths to success: networking and contributing (it’s all about relationships)
Largely because I think it’ll fit in with my presentation the following day.

Sesson 4 – Chris Atherton – Visual attention: a psychologist’s perspective
Not something I’m particular clued up on so will be an interesting session.

Session 5 – TBC
Nothing really catches my eye, and still waiting to see what Paul Ballard is going to present. Might a good time to go grab a coffee?

Session 6 – David Mackay – talking about how he wrote his book
Always interesting to hear how these things come about.

Thursday

Session 1 – Me!
I’m guessing I need to be at this one, right?

Session 2 – Nigel Greenwood – Quality Improvement in technical communication
A different take on things, and it’s usually informative to look at the way other professions do things, so this should be good.

Session 3 – Justin Collinge – The secrets of telepathy
Who wouldn’t want to learn telepathy! This will be useful as I’ve recently taken on Line Manager duties for some of the wider development team.

Session 4 – TBC
Either going for the session about localisation or the one on how to start up your own docs business…. hmmmm

Session 5 – TBC
There is still a slot to be filled, so I’ll wait until that happens and then decided. At the moment, its looking like an early end to the day.

Session 6 – Adobe
Will probably skip this as we are no longer an Adobe house.

So, add in the Gala Dinner and it’s a pretty busy couple of days. As ever I’m going to miss some sessions that I would liked to have attend but I’ve got a pretty good balance of things here, most of which benefit the company that is allowing me the time to attend, a couple of which will help me as a professional.

I’ll most definitely be twittering and will write some thoughts post-event as well. The chances of me blogging are slim but you never know (I’m wary that my 9am slot on the Thursday morning may be in jeopardy if I get ‘forced’ into the bar on Wednesday evening…).

I’m looking forward to the conference, my first ISTC conference as it happens, and as two other members of the team are off to Cardiff for the UA Conference it’s safe to assume we’ll be heading towards the end of the year a-buzz with ideas and enthusiasm.

Like most technical writing teams we are small in number. As such, monitoring and tracking both the work that needs done as well as the work that is in progress can be a challenge.

So I’m currently casting my net far and wide to find a good way to keep a handle on this so that I’m always reasonably up to speed with where we are in the grand scheme of things. Forgive me if the following isn’t particularly well delivered, as I am thinking this through as I type it up.

First things first, we need a plan. Actually we need two. One is a high level map of the documentation structure for the entire product so we always have a view of what we are writing and where it will go, and the map will include indicators about the audience so we know who we are writing for at a given time.

Then we need to plan the next batch of work inline with the development teams, estimating what new content is need and how long it will take. Alongside that is the daily churn of small bug fixes and enhancements, some of which will need to be documented, and the supported streams of older versions of the product as well.

The occasional request via email rounds out the various routes in which new items of work are generated.

I’m ignoring, for now, passing comments by colleagues (most times I’ll just email them to our team email alias to make sure we’ve captured the request).

So, project plans, topic breakdowns, bug fixes and open requests for more information. Nothing to out of the ordinary I’m sure, nothing that each and every technical writer has to deal with.

Which begs the question, how DO you deal with it all? Over to you, how do you track your work?

I’m currently scoping some work to provide a set of user guides for an application. The functionality is, mostly, split into two areas with one set for those administering the system and the other for those who use the system to complete their work.

Previously it would have been a matter of doing some task analysis, which would drive a list of topics, which would then be grouped sensibly, all the while keeping the audience of the information in mind. However, that tends to lead to an exhaustive list of topics, often leading to areas of the product that are little used.

To counteract that one thing I’ll be doing is initially limiting the scope to the production of conceptual information. Whilst some tasks will need a level of procedural steps, I’m more keen to get across the concepts and uses of the various parts of the product.

With this in mind I’m toying with the idea of using scenarios to drive the task analysis, taking the user through a few typical usage patterns and letting them learn the patterns of how the product works. It means that we are going to be relying on the design of our product (which is pretty good) to guide users appropriately through the application.

It’s a bit of a leap of faith, but is it enough? Time will tell!

The following are not in any particular order. Some are tips gleaned from experience, some are links to the knowledge being shared by others, all have helped us get us from a standing start to a full content conversion and production delivery in under 4 months. We started with ~2450 topics of imported content, and managed to keep pace with the development team as well as cleanup and backfill the imported content. Quite a feat!

Working with Author-it

As we were converting a LOT of content from FrameMaker to Author-it, there was a LOT of cleanup required. Being able to customise the styles toolbar, adding in the most common used paragraph styles for example, was a huge bonus. We ended up creating one under the Supervisor login, and then each team member copied that to their installation.

Apparently Prompt for unsaved changes is turned off by default. We found this out the hard way, so click the big Author-it A and check in the options to turn this on.

JavaHelp Tips

JavaHelp uses the HTML templates, so if you provide customised HTML templates it will use those.

This next one might be specific to the way our development kit works.

To get context senstive help working you need to add the agreed string to the Context String field on the Help tab of the Topic Properties dialog.

We used this on some topics that will only appear in the help system, allowing us to create ‘landing pages’ which can then direct users to the most pertinent topics for the area of the product they were using when they launched the online help.

MiniTOC

These are, by default, used in Chapter templates. To get better control of the layout of these (our issues were mainly with vertical white space, or lack thereof) we decided to not have any content in a Chapter topic. That way it is only used to hold/generate the MiniTOC and the next topic holds the first block of text for the chapter.

Terminology

To make it easier to reuse topics anywhere, we switched our terminology slightly. There is no such thing as a chapter anymore, unless you have Word/PDF specific topics. We use ’section’ instead.

Word template

The source of many a frustration, but that’s not really the fault of Author-it.

One thing I’d suggest you do first would be to figure out what macros you need and get them into the template first. Remember to configure the Publishing engine to use them as well.

We are using the following macros, all of which are available from the Author-it Yahoo Group:

• HyperlinkedTOC – creates links from the table of contents text, rather than just the page numbers
• RemoveCH – Removes the CH from the SuperHeading text
• ResizePictures – makes sure images fit the column width
• ResizeTables – make sure tables fit the column width
• SaveAsPDF – creates a PDF of the Word document

See how to Add an Author-it AfterPublish macro to the Word template for a simple set of instructions.

Problems with numbering? Julie Goodwin, Technical Support Team Leader at Author-it, popped up in a comment last month and pointed me at this solution.

Useful links

First place to head for information is, unsurprisingly, the Author-it Knowledge Center, it’s a replication of the entire documentation set plus some very useful Tips and Tricks and Workarounds.

After that, your next step should be the Author-it Yahoo Group. It’s active and full of hugely helpful and knowledgeable people and without their help I don’t think we’d have managed to hit our project deadline.

One member of the Yahoo Group, Rhonda Bracey, has published several excellent tips on her blog. Well worth a look.

A recent addition to Author-it, one we are currently looking at, are Variants. Hamish Blunck has an excellent overview of how Variants work, and there are more goodies to be found on his website.

And last, but not least, there is an official Author-it Blog which publishes product news, tips and tricks and other random stuff on a regular basis.

A few weeks ago Scott, from the always relevant DMN Communications blog asked me if I’d be interested in writing a guest post.

I immediately said yes then, after a short pause, I set the expectation that I wouldn’t be able to write one for a few weeks as I was coming to the end of a project.

So, last week I finished off my guest post and I’m now waiting, somewhat nervously, to see how it will be received. The post goes live on Wednesday, so not long left to find out.

It’s quite liberating, writing a blog post for another website (not done that for years), and it sparked a few ideas for this place as well. You’ll start to see some of those soon.

Thanks to Scott for the opportunity, and keep your eyes peeled to the DMN Communications blog on Wednesday.