Month: July 2009

Tracking Progress

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?

When is just enough?

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 impossible bike ride

My legs are pumping, sweat drips from my brow, trickling down my nose, my hands are slipping on the grips and through half shut eyes I watch the distance slowly rise.

More! Faster! COME ON!! I silently urge myself, blocking out the slow burn of acid in my muscles, pushing myself on, adrenalin surging round my body whilst I gasp for air.

The timer counts down, seconds to go, I know I won’t make it but I have to try, all the way, 100% until there is no time left, push push push, the pedals spin and my legs scream at me to stop.

The timer hits zero, I sit up in the saddle and gulp down air. Huge mouthfuls, a drowning man saved. My legs slowly calm as I slow down.

I look down at the display, hoping for the distance I want, the distance that was set, the target that spurred me on.

The LCD glows. 10.4km.

I silently curse.

I slowly cool down, stretch my legs and head home. Why can’t I do it? Why am I so far away from it? I’ve done it once before, mere weeks ago, what is wrong with me??

And then it hits me.

Two weeks ago I sat back after spending 40 minutes on the bike. I ‘travelled’ 12.1km. Excellent, I thought. A good target. Since then I’ve only managed around 10km, quite a drop, and it’s taken me until now to realise why.

I’m only cycling for 30 minutes.

My brain is trying to kill me.

The Picnic

The Picnic

It was a glorious day yesterday, wisps of cloud slowly meandered across the sky as the gentle breeze softly buffeted the long grass. Somewhere in Balloch Park a group of people were sitting on the grass, picking at various foodstuffs, drinking various concoctions, and chatting and laughing with nary a care in the world.

We were there as a wee celebration for my sister-in-law gaining her degree. She was quite tipsy by the time we left and apparently went on to the pub afterwards too!

It was a nice, relaxing day and I even found time to have a wee nap in the sun, dreaming of future picnics in the sun. All rather lovely.

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 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.


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.


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.

Smarty Pants

I wanted to mark today, specifically to mention here so I don’t forget it. My memory is lousy and no matter what the future may hold, I want to mark down today as a day I was inspired.

My sister-in-law graduated today and now holds a degree in Dietetics. I’m not quite sure what letters she can now use after her name, I’m guessing BSc, but I do know she got the equivalent of a 2.1 (but they don’t state that as she isn’t doing her Honours).

She’s not the type to make a big fuss over things, and chatting with her after the graduation ceremony she was quite calm and accepting of the fact. And why shouldn’t she be? She’s done all the studying, the essays, the juggling of placements around her work hours, so I guess she’s at the point where it’s a bit of a given that she now has a degree.

Her kids are all very proud of her, three of them were there today but unfortunately her oldest son couldn’t because he’s just (this morning at 2am) become a Dad for the first time, and I’m certain her Dad is thrilled and the only shame is that her Mum couldn’t see this day.

So, well done Claire. I don’t think there are all that many mothers who aren’t long past THAT ‘big’ birthday, have brought up four wonderful children, have kept down a job and who have just received a degree (which included a year of pre-degree coursework at college).

I have to admit I had a little pang of jealousy as, having not found my passion until later in life, I didn’t finish my degree (Electronic Engineering for what it’s worth… not much, trust me!). It might spark me into pursuing that MBA I’ve been eyeing up for the past couple of years.

Regardless, I’m chuffed to bits for her, she’s worked her ass off these past few years and I’m sure the true sense of her achievement will start to sink in soon.

And I’m really not trying to bask in her glory by suggesting that proof-reading her essays was what really made the difference, honest I’m not…


I almost shrieked like a girly girl. There it was, floating a metre in front of me, within touching distance, if I just stretched out my hand I could probably feel it under my fingertips. I wondered if anyone would notice and, glancing around, I saw the same look of wonderment that I could also feel plastered across my face.

Yup, there was no doubting it. Floating in the space between my seat and the cinema screen, the Nickelodeon logo was slowly revolving and looking very 3D. Ohh sorry, very RealD.

It was quite awesome. I wish I could find some better words but, like, seriously, it was AWESOME!!

All very impressive and that was before the movie started. The movie, Ice Age 3D, was about Mammoths and Dinosaurs, some cute baby dinosaurs, a cute baby Mammoth, had no real plot but a few giggles and on that front probably met all its requirements, although to be honest, it was a largely secondary affair to the technological wonder of the evening.

I can remember when Jaws 3D came out and how underwhelming the experience was, there seemed to be a disconnect between the 3D elements and the movie which broke the suspension of disbelief, never a good thing.

But last night, once I’d gotten past the schoolboy amazement of seeing things float out of the cinema screen, it struck me (not literally, it’s 3D but it’s not THAT good) that it felt natural and connected to the movie I was watching. Ohh of course there were a few gratuitous “lets put some grass at the front to show off the 3D-ness” moments but pretty soon it stopped surprising me that some of the characters seemed to be sitting in the front row of the cinema.

I can also happily report that George Lucas will soon be remastering the entire Star Wars franchise in RealD. Well, if not, he probably should given that one of the chase scenes (featuring flying dinosaur type things) was a straight rip off of the Pod Race which was so FREAKIN AMAZINGLY AWESOME that I almost wet my pants as the winged dinosaurs flew past me, into the screen and beyond at a zillion blurry miles an hour. AWESOME!

So, all in all colour me impressed (which I believe is just a bright purple).

It’s not all roses though. Some of the trailers were in 3D whilst the animated movies looked OK, those feature live actors looked like the reality was being forced, like there was a deliberate effort being made to introduce depth where none was needed.

Safe to say though that I was hugely impressed and the novelty of watching items from the movie float around and leap past me easily got me through the movie. The fear is that it will be just that, a novelty.

Guest Posting

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.


A large chunk of the weekend was spent clearing out our garage. We’ve not done if for a couple of years and by god it needed it, full of crap it was. Pots of paint with only an inch left in them, some broken garden electrical equipment, and old tumble dryer, random bits of wood, and some garden rubbish and rubble all bagged up and left over the winter.

Three trips later and I can finally walk from one end of the garage to the other without tripping over anything, quite a danger when said garage is home to various sharp and pointy garden tools. It’s the kind of job that is a real chore, especially on the first full weekend I’ve had off for a month, but now that it’s done I do have a small sense of achievement.

One thing is evident though, we do not recycle enough.

Our local council run dump is an organised affair with several different places to put all the different kinds of ‘rubbish’ which a dump receives. Glass here, wood there, plastics over there, electric items in that skip, white goods in that one, fridges on the left, and grass cuttings and other green waste in that big area at the back.

I can remember a time when a visit to the local dump was occasionally an opportunity to find something for free. The headboard on my childhood bed came from the local dump, and was in perfect condition. Alas this doesn’t seem to be the case anymore.

For example, we found a small box of leftover tiles from when we got the kitchen done. We kept 5 or 6 for ourselves, in case of breakages, and put the rest in the car to take to the dump. My thinking was I could leave them at the side and maybe someone else could find a use for 20 or so tiles that were left. Alas this was not to be the case as, upon arrival, the ‘helpful’ council worker told me I couldn’t just leave them lying, into the skip they must go!

Pardon the pun, but what a waste.

Of course it’s really down to me whether or not I try and recycle that kind of thing. Perhaps freecycle could’ve helped? Or a form of car boot sale or… well this is my point. How else would I get rid of such things? Put an advert in the local paper?

No, far better to throw it away, make it someone elses problem. Right?

I’m quite ashamed, to be honest. Whilst a lot of what we threw out was rubbish, there were a few things that could possibly have been reused. I wonder how I get to the point where, instead of only pausing before hurling that old table over the barrier into the wood-only skip below, I actually stop and reconsider.

Given the evidence at the dump, it’s safe to say that I’m not alone. That whilst a lot of what I saw there was broken, unusable trash, there were items that could be reused by others. Sometimes I feel bad for our planet, that we abuse it so much.

But apparently, I don’t feel sorry enough.