Category: Work

Ever wanted to just throw everything away and start over?

I’ve been tempted by this notion recently and, whilst it may seem a bit ill-conceived, part of me does wonder what would happen if we just, quietly, started removing some parts of our documentation.

In fairness, we’ve done that in the past. Our Development Kit has many aspects to it but, applying that old favourite 80/20 rule, we realised we didn’t need to maintain or even publish documentation on every single function point.

One of the reasons for the current line of thinking is that, quite simply, we have too much information. There are too many places to find information about our product, so we are refocusing and slimming down our offerings to make it easier for our customers.

This is a change of direction for us. When I first joined this company, to start building a team as there were no technical writers with the company when I joined, I inherited a lot of legacy documentation, not all of it particularly useful (my oft quoted example was finding one single page of documentation for a particular Tool in the Development Kit. One page for an entire tool packed with functionality, that you launch in the same manner as every other Tool in the Development Kit, which told you … how to launch the Tool. Useless much?). The challenge on joining was to improve the quality and coverage of the documentation.

And we’ve been very successful! We have a rich set of information available, but over time it has, as it always does, started to degrade. We have added more and more and, whilst we have consolidated where possible, the pace of product development here means we are usually hanging on to the coat tails of the next release.

So, with some changes to responsibilities and a shuffling of resource we are now in a position to take stock and start removing content and completely overhaul the structure of what we deliver. That will help improve findability (our main aim) and by focusing on the content that is really needed we can improve the quality as well.

It may also mean a change of authoring tool to support the outputs we want but more on that, later.

http://www.istc.org.uk

It’s Friday the 13th (still!) what better day to announce that the new ISTC website is going live.

I have just updated the domain nameservers to point to the new website. It can take a day or so for these things to propagate through the Internet so it might not appear immediately for everyone.

If you experience any problems or spot anything that needs corrected please let me know.

I have still to upload all of the InfoPlus and Communicator archives, but aside from that, the rest of the content should be available.

http://www.istc.org.uk

Call for Papers for TCUK 12

Dear reader,

You are an intelligent person, have you ever considered sharing your knowledge with others? Perhaps doing a short presentation at an industry conference?

Regardless of your experience, or industry, the Technical Communications UK conference wants you!

New speakers and experienced speakers – all welcome

Regardless of whether you want to present for the first time or you are a seasoned conference speaker, we want to hear from you. We don’t mind if you are new to technical communication or if you have worked in this field for ever, if you have something to say to other technical communicators thenTCUK 2012 is your chance to say it.

Industry sectors

Technical communicators work across a wide range of industry sectors, including engineering, aerospace and defence, transportation, services, retail, charities, and government agencies as well as in hi-tech industries. TCUK 2012 is the conference for everyone who works in communicating technical information of any kind.

This year’s specialist stream

Two of the streams are open to topics of general interest to anyone in the technical communication industry. The specialist topic for this year’s third stream is Accessibility and Usability. Proposals for presentations within this area are particularly welcome.

There is one week left before the deadline, so get moving!

More information here: Call for Papers for TCUK 12

Last night on Twitter I asked “Looking for a way to tag topics in an authoring platform. Not part of Author-it, does any app do it?” and a few helpful people gave me suggestions.

I later clarified and thought I’d expand on that here. My clarification was that “Re tagging: we want to tag topics in the authoring tool so whatever the output, the user can filter on tags eg, v1.0/email or v2.3/document”, it was at this point I realised I needed more than 140 characters to explain what I was looking for…

Our product is in the throes of moving to a modular/component delivery. We will no longer have one installer to install one big product with everything in it, instead you will likely (it’s still being figured out) get a core application which you can then enhance with additional modules.

The challenge to our team will be to document this product in a way that is useful to both the people who might use the application and to those people who customise the application for specific customer needs (which may or may not involve customising a module or creating a bespoke module for a customer).

One idea that may help us in this would be the ability to tag all of our content with module/component/functionality tags, and a version tag. There may be more tags required but we can figure those out later.

However, the authoring product we currently have, Author-it, doesn’t offer this functionality. We have looked into a way of manually doing it by hacking XML files but it’s less than ideal.

So what I was asking for, badly, on Twitter was a native application that includes tagging of topics on the authoring side, with the tags then available in the output. Ultimately we want to be able to build dynamic sets of information AND allow the users to change the view of the information based on the tag(s) they’ve chosen as well.

MadCap Flare comes closest as it at least has a notion of ‘tags’ in the product but not sure if that allows a dynamically built output, and Robohelp allows tagging of returned search results but no way of producing that content dynamically.

Does such a product exist? It  feels like it should, that it’s not a million miles away from what a lot of technical writing teams would want… but I don’t think it does. Prove me wrong!

It’s going to be a big year for us, both as a company and as a team. We have grand and achievable plans for the product which will mean the working processes for the Publications team will need to change for, as well as multiple streams of work with their own staggered release dates for the product, we are also restructuring our entire information set to improve ‘findability’.

Which immediately prompts a question, how do you improve ‘findability’?

The simple answer is would be ‘in as many ways as possible’ as there is no silver bullet. What may work for some, won’t work for others. However we have to start somewhere and the first thing we can do is restructure the architecture of our information, slimming down the content where possible with an eye to adding new formats of information.

We have already successfully piloted some new formats of information and will continue to roll more of those out for different areas of the product (in essence, these new documents are a high level overview of all the levels of an area of the product, from concept and usage to API implementation), and the signs are that the restructure will go a long way to meeting the needs of our customers.

Having been lucky enough to speak directly to some customers in the latter half of last year, I know that we are on the right path. The challenge will be to keep moving things forward amidst everything else. It’s going to be a busy year and already the analogy is one of a juggler who is keeping things in the air… for now!

The next ISTC West of Scotland area group meeting in Glasgow will take place on Thursday 16th February 2012, from 7.30 pm onwards. Come along to talk about latest news and trends in communication, or just to meet other communication professionals.

The event is free and open to anyone interested in technical communication, such as technical authors, information architects, internal communication professionals, report writers, marketing writers, web content writers and graphic designers.

Venue: Waxy O’Connors pub, 44 West George Street, Glasgow, G2 1DH. Please make your way to McTurk’s Room on the middle level.

If you plan to attend, please sign up for the event at http://www.eventbrite.com/event/2743613221 to help us anticipate attendance numbers.

Please forward this message on to your colleagues or anyone else who may be interested. For more information, contact westscotland_areagroup@istc.org.uk.

UPDATE: MadCap have provided a licence of MadPak, worth USD 1499, to be raffled amongst event attendees. For more information, see http://www.madcapsoftware.com/products/madpak/overview.aspx