TCUK10 – quick guide

This is an update to a previously published post. Not all of the sessions are scheduled yet, so I’ll update this as and when but, if you are wanting a quick print out of the session to, for example, convince your boss to splash some cash, then hopefully this PDF will do the trick: Technical Communications Conference 2010. (Note: a similar PDF is also available from the conference website but I think mine is prettier :p)

Continue reading

Remembering the basics

What do you call your documents? What is the first thing you do when you start writing? What is the last? All these things that you do without thinking about, the basic automation that your brain easily handles, over and over again, these things are, to you, so basic as to be forgettable. You don’t tell anyone else to do them (they must know, right?) and you probably don’t remember where you learned how to do them. You bulid your own mental checklist and that takes care of that. Need to provide a PDF of a document for someone? No problem, generate it this way, name it in this manner to keep it sensible and consistent and put it THERE …

Continue reading

Analyse this

Let me tell you a story. In it our hero (me) fights valiantly against two Javascript dragons called Webhelp and Google Analytics. It’s a bloody battle and at the end, when all the fighting is done, well … you’ll have to read on and find out. Some background first. We have a developer community website which hosts downloads of our software and all the documentation in PDF format. To make it easier for people to find information in the product documentation, we also host a Webhelp version of each and every document in one master Webhelp system so you can search across the entire thing. It works really well. To track how the other areas of the website are used, …

Continue reading

Technical Documentation Know-how

A few days ago I received an email about a new website. I’ve seen it mentioned on other blogs but think it’s worth repeating as there is some useful information there. I am contacting you because I have just thought that maybe a post about my new web site on software documentation and user assistance could also be interesting for your readers. In addition to about 250 useful links for technical writers, the site for example provides checklists and up-to-date market surveys of more than 350 help authoring tools, screen capture tools, screencasting tools and other utilities for technical communicators. All information can also be downloaded as a PDF booklet (approx. 100 pages). On the website you can find some …

Continue reading

Access is good

Yesterday we launched a new version of our developer community website. It doesn’t have many ‘community’ features as yet but that’s all to come. One thing it does now have is an HTML version of all of our product documentation, in an easily searchable format. It’s no coincidence that it looks very much like the Author-it Knowledge Center as it too was built using Author-it (alas I can’t show you our website as it requires a login). This new format of the product documentation is largely to move us away from PDF only documentation. At present we still have a set of PDFs but they aren’t particularly usable. We ran a few quiet trials of the knowledge centre format and …

Continue reading

Dumping the manual

I honestly can’t remember the last time I picked up a user manual, an honest-to-god paper book of technical documentation. Actually that’s a lie, it was just last week when i was tidying up. I picked up several user manuals and moved them to a lower shelf on my bookcase. It’s also been a long time since I last worked for a company that produce and printed user manuals but that’s more to do with my career path than any decisions I made within those companies. Even now whilst we have a “documentation set” comprising several different user manuals, it’s published to PDF and made available as part of the product distribution (and also online). So why do we still …

Continue reading

Paper based

I am a paper junkie. I’m a whore for a nice caliper of paper, not too thick as to be card, not too thin as to be unsubstantial. I love the feel of paper, the rustle and rigidity that give way with a subtle movement. I love the sound of ink being laid down, the gentle drag as my hand loops and dots across the page. Despite all the advances of modern technology, I don’t see this changing. In fact I’m such a slave to this way of thinking that I’ll often print off an email if it contains important information that I’ll need at some point in the next day or so. As such I walk around with a …

Continue reading

Author-it Hints, Tips, & Useful Info

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 …

Continue reading

Planning your deliverables

I don’t like making presumptions, something that I learned early on in my technical writing career, but I am going to presume that anyone who reads this knows that they should be planning what content they produce before they start writing. You do, right? A basic information plan will include knowledge about the audience, the main areas of the information that need to be covered for the project/release, as well as outlining the purpose of the documentation and any media and design considerations. Finally you’ll most likely provide a definitive list of deliverables, be they printed documents, PDFs or online help. It’s this last area that I’m currently working on. Our product has undergone some exciting changes, and the previous …

Continue reading

Why we are moving to single source

I’ve waffled on about single source and our plans for long enough so, as we are finally starting the process itself, I thought I’d capture some information as we go along. However, it’s probably good to set the scene, so I’ll cover that stuff first. Over time you’ll be able to see all the posts related to this work here. Why? – why single source? A quick summary of our current situation. We currently maintain (and add to) ~2000 pages of documentation. The same content is used for both the PDF manuals and the online help provided with the product (exactly the same, no restructuring). There are various levels of coverage (some good, some bad), we are embedded within an …

Continue reading