bookmark_borderWhat not to do

Working in a team that isn’t heavily invested in documenting requirements and specifications (we usually have a starting set of such things but these soon fall out of step as development evolves) makes it a challenge to know both what is being added to the product and whether it needs to be documented.

The development teams recently adopted JIRA and whilst the additional information helps I fear it may give us a bigger problem. As we will (should?) finally have a clear picture of everything being added to the product, will it be too much for us to handle?

At present the Publications team have two very large products, with a complex API and code base which is all evolving and which needs to be documented. We cover a mix of SDK style documentation, reference information as well as procedure based topics and many conceptual pieces. We don’t document all of the product at the moment but it’s fast becoming apparent that deciding what NOT to do will be a vital skill as we move forward.

We can’t, and shouldn’t, document everything but a firm focus on making sure we are providing the most value (bang per buck!) helps us make better decisions about what we can ignore, and what our customers really need.

How do you cope with the ever increasing pace of development? What don’t you do?


I cannot be bothered with faff.

This is one personality trait that has definitely changed as I’ve gotten older, or perhaps it’s just a reaction to the years I spent indulging my ‘gadget-geek’ and allowing myself to think that jumping through 5 hoops to get a simple task done was “OK”.

My mindset these days is very much that technology is there to serve me. If something starts getting in my road I’ll work around it, or replace it completely, ruthlessly.

I’m about to talk about a technology company which I know some people don’t like, but bear with me.

I have an iPhone, an iPad, Apple TV and an internet connected Samsung TV. The bulk of my content consumption happens through those devices. I have a desktop PC, running Windows 7, which is where all of my content creation occurs. More of my time is spent consuming content so I recently bought a NAS drive to allow me to remove the desktop PC (and it’s large hard drive) as a middleman.

I can now watch movies on my TV that I created (ripped from bought copies) on my desktop PC as they now live on my NAS drive. I can view photos the same way.

I can also browse and play music from my NAS drive using my iPhone, or iPad. Unfortunately I can’t hear it.

My plan was to use an Airport Express, connected wirelessly to the NAS box, with audio out to a dedicated set of speakers. I have an old (“g” standard) Airport Express and bought some new speakers (AudioEngine 2).

Alas, the plan is failing and whilst I’m still not sure why, it’s getting the Airport Express setup that is causing the problems. That might be down to the Airport Express itself, or the Windows box, or even the router (a Thomson box supplied by O2). I’ve tried every set of instructions I can find but still nothing.

What are my options now? I could buy a newer Airport Express in the hope that works easily, or I could buy Airplay enabled speakers and be done with that extra step.

Too much faff ya see. If it had just worked I wouldn’t even be moaning about it here.

bookmark_borderIt's not easy being green

Last year I flew to America (visiting Boston and Chicago) and this year I’ll be flying to London (twice) and to Singapore later in the year. I’m travelling much more than I used to so I guess it’s only natural that I’m pondering how to rebalance my carbon emissions.

This definitely played into my decision making when I recently changed cars and whilst it wasn’t my main focus, I was pleased to get a hybrid engined car (petrol/battery). It’s also a nice side-effect of getting fit and cycling to work now and then (not as often as I should mind you) that I don’t run my car as often either.

However, to properly rebalance things I need to do more. Recycling at home is one thing but given the air miles I’m clocking up I’ve been looking at other options.

On the face of it, it looks quite straightforward, carbon offsetting through something like carbon credits seems to be the right thing to do but, as ever, when you start to dig a little into the motivations behind some of these things and part of me does agree that all I’m really doing is ‘buying absolution’.

So what to do? Stop flying to far away places? Having not travelled much beyond Europe until recently (one trip to San Franscisco 11 years ago this feels a little bit harsh but no, I’m not suggesting I’m in ‘carbon credit’ already. Perhaps the bike thing is what to focus on first and foremost?

Anyone else got any ideas/suggestions/thoughts?

bookmark_borderTCUK 12

The time has come, so Gordon said, to talk of many things, of slides and chats, and learning facts, and something else that rhymes but I’m rubbish at poetry (with sincere apologies to Lewis Carroll).

Enough of that though, what I want to talk about is the Technical Communications Conference 2012 (TCUK12) and why you should go.

Disclaimer: I serve on the Council of the ISTC, who organise this event. 

Let me tell you a story.

Once upon a time a young (ok, middle-aged) man had started a new job and was trying to figure out the best way to improve things and solve some of his problems. The year was 2007.

At the time, the young man (oh shut up) had started a blog and was finding a lot of interesting people writing about Technical Communications. From that he heard about something called DITA. To learn more, as it sounded very much like it might solve his problems, he went to a conference (X-Pubs) in Reading. He learned a lot, and met a lot of inspiring and interesting people. Turned out DITA wasn’t for him though (yet).

Later that year, he had the opportunity (entirely thanks to his blog and a lovely woman named Anne Gentle) to attend and speak at TICAD, an opportunity that came about directly through this blog. It was a smaller conference in scale but just as rich in information.

Having set a precedent of attending conferences, he looked around for another the following year and, remembering how good he found the Digitext conferences (many years ago now) he decided to attend the User Assistance conference in Edinburgh (2008). Again, he found himself surrounded by his peers, and took away some valuable lessons.

The following year he heard of new conference, and as it had multiple streams of presentations he thought that would give him the best chance of learning. He also felt foolhardy enough to present at it (but let us not dwell on that). The conference was called Technical Communications UK (2009).

And that’s quite enough babbling about me.

It’s always interesting to see what presentations and theme the conference will have, each year has had a different third stream, and this year it’s focusing on Accessibility and Usability, something I know many technical writers working in a software environment inevitably get drawn into (if it’s easier to use, it’s easier to document). Add in the longer workshops on the first day and, for the money, it’s hard to beat.

Like many people I’ve had to convince my boss it is worthwhile letting members of our team attend, but I’m convinced that everyone will find a handful of topics that they could learn about and look to apply at their own workplace, the trick is to plan to do just that.

Any time I’ve ever returned from a conference I’ve been excited and looking to apply ideas and techniques to what we do. If we hadn’t managed to implement some of these things then it would be much harder to ask again the following year as the evidence of value is a hard thing to argue against!

Above all though, TCUK seems to have a good energy, a good ‘vibe’ and everyone who attends seems that little bit more driven and up for learning, discussion and basically getting stuck in. I does help that most people stay over so you start to make friends over a glass of wine (or three) and that carries through into the next day giving the entire conference a relaxed, friendly feel.

If you only plan on attending one conference this year, I would heartily suggest TCUK as a great starting point.

Hope to see you there!

bookmark_borderAll change!

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.

bookmark_borderBack from Tunisia

We did done a holiday!

We had a few simple criteria for our holiday. It needed to be under £500 each, it needed to be somewhere hot and sunny, and ideally it needed to be all inclusive.

After various online searches, we had it narrowed down to a week in Cyprus, or a week in Tunisia. helped keep the price to just under £400 pp and we ended up picking Tunisia as it was a bit different (and Kirsty has been to Cyprus before).

It’s safe to say we lucked out and had a fantastic holiday!

We stayed at a hotel that was built in the 1970s, built in the style of an old Medina, mostly two stories tall and sprawling over the area of a small town, it was Tunisian to the core. Driving past other hotels in the area (Yasminne Hammamet) and I have to admit it was nice to be in one of larger hotels (the more typical Costa del Sol style, 6-8 floors with boxy rooms).

The room upgrade helped too, of course.

I’ll admit that I wasn’t quite sure what to expect from Tunisian but I’d heard good things about the country and the people. I wasn’t proven wrong. The Tunisian people were friendly and, with a few words of faltering Arabic, always ready to help with a smile and a laugh.

The hotel itself was great, the staff efficient and an enthusiastic ‘animation’ team meant there were plenty of activiteis for us… to largely ignore (we did a bit of archery but our focus was to be lazy!), the food was great and well enough varied that you never got bored, and the sun did it’s bit and for the most part shone brightly, keeping things at toasty 28C or so (we think we topped 30C one of the days).

I ate camel steak, bartered in the souk (and no doubt still got ripped off), visited Carthage and Sidi Bou Said, had a wonderful Turkish Bath and massage, and did a whole lot of lazing around and chilling out.

In fact the only negatives were the security queues at the Enfidha airport, but such is life.

I’m back home now, feeling properly relaxed and upbeat, with a reasonable tan (we were only there for 7 days) and a desire to go back again. The resort itself is very similar to Andalucia, there is a Moorish influence to be found, and a similar climate. Learn a few basic Arabic phrases and don’t get put off by the sellers in the souk, it’s part of the fun to chat with them and avoid getting dragged into their stores ‘just for a look’.

I’d happily, highly, recommend it for a sunshine break. Yes, it was a package holiday, but with excellent customer service, it really did feel like we got a lot of value for our money.

Some of our memories of Tunisia.