Category: <span>Work</span>

A new year, a fresh challenge.

I’ve been working in the Technical Communications field my entire career. From those first days, stumbling my way around FrameMaker 4 with only a vague idea of what I should be doing (and largely using the FrameMaker User Guide as a sample of both approach and layout) to my current incarnation as Product Information Manager which involves running a team of 6 technical writers, looking at what other services we could offer to other parts of the (now) global organisation I’m part of, not to mention running a developer community website and generally advocating a product view wherever possible.

Actually, make that my previous incarnation.

As of today I’m changing roles, with a new job title of Product Operations Manager.

I’ll be working within the Product Management Team dealing with operations issues, planning and so on, and generally helping the Product Managers, and Senior Architects do their day jobs (the phrase ‘herding cats’ has been used on more than one occasion so far).

It’s very exciting, a little bit scary (in a good way), and a big step out of my comfort zone of technical communications. Whilst the principles of managing a team with multiple deliverables and differing focus areas is something I’ve been doing for a while, it’s good to have a new challenge.

The new role will take me away from technical communications, and whilst I’ll still retain a passing interest I know myself well enough that it’s only a matter of time before I lose track of developments and trends altogether. I am a sucker for new things!

I’m not sure what that means for this blog, or my other interactions with the technical communications community, but I’ll figure that out in good time.

Meanwhile, I’ve got a job description, a new boss, new teammates and a whole new world to get my head into and it’s all kicking off this week. Hence why I’m sat in a hotel room in Sunnyvale writing this blog post.

Anyway, first things first.



One of the challenges the team will face this year is how to coordinate the creation of product documentation with geographically dispersed teams, across different product lines.

At present we have engineering teams in Glasgow, Belfast, Limerick, Jakarta, Sunnyvale CA, and Bedford NH, building four products and maintaining five other legacy applications. Currently we have six technical writers in Glasgow and one in Belfast. Initial assessments suggest there is a bit of a resourcing gap (a separate issue I’m dealing with) but beyond that the main challenge will be figuring out how to best work with these disparate

I have asked this question in a couple of places and had some excellent responses. Some cover things we had already considered but there were some gems borne of real life experience that I was lucky enough to have shared with me. Many thanks to Tom Marshall, David Farbey, Cheri Mullins, Larry Kunz, Alan Bowman, and Kay Winter and others for their suggestions.

First things first though, and it will be important to discuss and agree on responsibilities, tasks, and roles. Naturally there will be a level of autonomy, so it makes sense to have sensible agreements on what issues require escalation and so on. Part of these early discussions will also need to include tooling agreement, writing styles and output formats. Ideally these can just be extend from what the team currently uses but that will have an impact on both sides.

The timezone is an obvious issue which could have a dramatic impact on communications between the teams. Case in point, the teams in Bedford and Jakarta have a 12 hour difference! So one of the first things we will need to do is consider, as we won’t have the luxury of immediacy, is a ‘rules of engagement’ or contract between teams as to how we will correspond, talk, meet and share information. Nothing too formal, but setting out expectations will do no harm. For example, when sending out an email should you expect an acknowledgement? Or should everyone have ‘read receipts’ enabled?

Some of the challenges we may face we already have solutions for; we use Google Docs for collaboration, we have conference lines ready, our engineers use a common JIRA install.

Thankfully there are numerous technologies that can help us with communications:

  • Everyday – Instant Messaging – for a quick question or two, and as a way to see who is available (and how you are working with), IM is a useful tool. Add in file sharing and it becomes a little more powerful.
  • Information Sharing – WIKI and Google Docs – for collaboration we’ve had good success with Google Docs, but there is no reason a WIKI couldn’t fulfil the same role.
  • Meetings – Skype or Google Hangouts – Skype nicely doubles as an instant messaging app, which also allows you to send files and of course you can host conference calls there. Recently I’ve seen some friends have success with Google Hangouts (part of Google+) which, as most laptops come equipped with a webcam these days, might be a good option too.

Not to forget the trusted old telephone! Ideal for a 5 minute catchup every day or so.

And, of course there will also need to be face-to-face meetings on a regular basis to make sure the technical writers feel part of the team, that includes organising social activities as well.

Other suggestions I heard, and which are worth heeding:

  • Regular conference calls – Make sure these have an agenda and that everyone has prepped beforehand to maximise usefulness.
  • Access to latest builds of the software – in our office we can checkout the latest build of the code any time we want, no reason remote technical writers can’t do the same.
  • Be sensitive to cultures, both professional practices and social niceties.
  • Adjust for time zones.

There are many pitfalls ahead and whilst I have great confidence we will figure them all out, obviously the more we can spot up front and negate, the better (and cheaper) the end solution will be. As ever, I have the advantage of working with smart people so I’m confident it will work, once we figure out exactly how.


The festive season is upon us, cards have been posted, presents have been bought, and in a couple of hours I’ll head home, leaving work behind until early January.

2012 has been an interesting year.

We started the year with a challenge, one of making the information we produce ‘findable’. Cutting across more than 20,000 topics of information, it was always going to be a big project, particularly as we still needed to keep up with product development. As the year draws to a close the final pieces of this mammoth project are falling into place and should, fingers crossed, be launched in the first couple of weeks in January.

From my viewpoint, it’s been an excellent example of giving people the space to do great things. I’ve not interferred much with this project, gently pushed it when it was needed, made decisions when required but by and large left the team to get on with it. The results are looking good.

Of course plans were impacted when the company I work for was merged with KANA software. Thankfully it was, for us, a mostly seamless experience. The day to day activities of the team haven’t changed (yet), but there has certainly been a lot more for me to pick up as the requests for documentation resource started to come in from other parts of the organisation. We are still figuring out how best to provide a service but it’s already looking like we will need to hire to backfill some gaps in other geographies.

Elsewhere I finally managed to get the new ISTC website launched, and have since enhanced it in a few places, adding in new Area Group pages, and generally beefing up the functionality in the background. Plans are coming together for the next set of changes so keep an eye out for those.

So, plenty to keep me busy in 2013, and that’s without covering off the building of a new community website at work …

One highlight for me has been getting back into the blogging habit here and generally feeling a bit more excited about my profession, hopefully I will continue to get a lot of value from sharing my thoughts here in the future!

That said, I’m off on holiday now but will be back in the first week of January. If you celebrate it, have a very Merry Christmas, and all the best to you all for 2013, thanks for reading!!


Comments closed

Yes, I know, first world problems and all that, shut up…

With the news that Instagram can now start selling my photos, something I didn’t agree to when I signed up, I’ve been looking at what services I use the most and wondering if I might be better to switch all my online/digital actions to only use paid for options.

Don’t get me wrong, I understand the need for companies to make money and that offering services for free isn’t ever going to be properly scalable until you reach a critical mass (think Facebook and Google). What really irks me about the Instagram change is that I don’t have an option other than to stop using it and delete my profile. If they’d given me the option, I’d likely have paid for it.

That got me thinking, could I switch to only using apps and services I’ve paid for?

I use Twitter, Facebook, and Instagram for most of my ‘social’ activities. I’ve recently gotten back into FourSquare (as I pull the data into the journalling app Day One) but it’s not really something I’m using socially, it’s purely a tool to make up for my own, shockingly bad, memory! I use several Google services, Mail, Docs, Calendar for my personal information management.

I do not pay for any of these services.

I use Evernote to capture incidental data, notes and links, and the wonderful Dropbox (try it!!) to sync files between all of my devices (personal and work laptops, iPhone and iPad). I have an iTunes Match account to host my music in iCloud.

I pay for all of these services.

So I guess the question is, can I replace Twitter, Facebook, Google and Instagram with paid for options?

For many years I’ve paid for a Flickr Pro account. It was one of the first services I used that even offered a ‘paid’ option (I was still using Blogger at the time) and thankfully, it seems to be going under a bit of a revival. I looked at alternatives (500px) but with such an investment in time, I’m happy to stick with Flickr. The Flickr app seems pretty good, and I’ve also got the Camera+ app on my iPhone which has allows me to upload photos to Flickr. That takes care of Instagram.

When it was announced, I paid for access to, a pseudo-replacement for Twitter. Whilst I’ve not really gotten into it, perhaps all I need is a bit of a push (and for more of my friends to be using it). I’m not ruling out Twitter just yet but as it continues to look to lock down it’s system, I’ve no doubt there will come a tipping point which pushes me to ditch it.

So what of Facebook and Google?

I can replace the latter for the most part, a combination of Dropbox for documents, my own mail server (part of the hosting account I pay for as part of this blog) and the calendar is already driven from my work Exchange server (it just syncs to Google). I’m not inclined to leave Google though, their ecosystem works well.

That leaves Facebook. I’ve pondered deactivating my account there before. I get some value from it, as I have friends and some work colleagues on there, not to mention my family. What value does it have? Well that largely comes about because ‘everyone’ uses it. Organising a get together or a trip is pretty easy if everyone has a Facebook account. The problem with only me closing my Facebook account is that my friends would still use it and I’d likely miss out on news and events in my social circle (well, one of them at least). Sure I could try and convince them to use Google+ (which is definitely improving) but that’s not gonna be easy.

Other than Instagram, I’m not making any decisions right now. I can see a time when I delete my Facebook account, but as someone said, I’ve not yet accounted for the next cool new service to come along (although they are increasingly looking more like aggregators than anything ‘new’). Time will tell but at least it’s good to know there are options out there for when a company pulls a fast one and leaves you with little choice but to seek alternatives.

There is a couple of weeks before I need to close my Instagram account though, and whilst there is still time for them to back track and for it all to be deemed a big mistake, the fact this was allowed to happen at all is what leaves a bad taste in the mouth.

Bye bye Instagram.


UPDATE: Instagram have published a clarifying post, stating that there intention isn’t to sell photos and that the wording wasn’t great in their original T&C update. I disagree, I think the wording was very clear (I’m not alone in this) and so whilst the words may have changed, the intention to monetise Instagram is clear and understandable. For me, it’s not a question of them being ‘bad’ for trying to make money, it’s the lack of options for me, the user. If anything, whilst I probably could keep using Instagram, the whole affair has given me a bit of a kick. It’s very easy to ‘rely’ on a free service then grumble when it changes.

Tech Work

In the New Year we are instituting a No Talking rule in my office. If anyone has a question, they have to write it down and pass it to a colleague who will then write down their response. This should cut down on the amount of chatter and conversation that, obviously, is having a huge impact on productivity.

There will be no more talking in our office, the conversations will stop!

I am, of course, joking.

What I’m actually pondering is how to extract the casual knowledge that currently exists in the heads of the development team. The little snippets of information that take seconds to utter when prompted by a nearby colleague, but which remain out of the grasp of the product documentation and thus are invisible to anyone not sitting in our office. You know the type of thing:

“Hmmmm, hey Alice, my build failed with error 4932, any idea how to fix it?”

“Ohh sure Lewis, just set property 73 to false and it should run just fine.”

The above names have been changed to protect the innocent.

This kind of conversation happens everyday, across the breadth and depth of our (very large) product and, as we have development teams around the globe, it is a real problem and one we need to solve.

The No Talking rule might sound ridiculous but it may be one way to help people realise just how much information they impart to each other, face to face, that isn’t captured anywhere else. That’s the theory at least.

I work with smart people, they are friendly, helpful and professional. They go the extra mile and genuinely want to do a good job. I’m not just saying this but they are one of the best groups of people I’ve worked with, but that doesn’t change the fact that they way they work is flawed.

Ultimately the challenge will be to change the culture, just enough, to be more info-centric. For example, if the software build system breaks, the developers fix it, yet it seems obvious to me that our information channels are broken and my perception is that they don’t care enough to want to fix it.

How do I get them to invest in this idea? Talking to my girlfriend she rightly suggested that one method that might work would be to pitch it as a time-saver. If every developer was to count the number of questions she was asked over the course of a week, I think they’d all be surprised at the number. Whilst not all of the questions would be something that needs documented, I’d warrant a fair number would be. As I said to a during a discussion with a couple of team leads last week, I’d much rather my team was inundated and overrun with requests to add information to the product documentation, at least that way we’d know the size of the problem.

So maybe I will suggest a no talking day, or maybe there is another mechanism out there that the developers will buy into. Maybe the first step should be to ask them what they think, are they even aware this problem exists (I’m sure they are, it’s just not the most pressing problem in their day to day list).

Regardless, one way or another, it’s something we need to fix, preferably without stopping the conversations.


I’m currently cruising high in the sky above the USA, on my way from San Francisco to Boston. It’s part of a whistle stop tour of two of our offices here which have teams of software engineers, architects and product managers (no technical writers though) that are building part of the product we will be shipping early next year.
During a chat with a couple of the product managers there was an interesting revelation. In describing the approach the team takes when it comes to writing documentation, the two product managers both smiled with relief when I said that we didn’t really spend much time on simple procedures, instead we try and concentrate on the why, on decision support information. We work with the support team to catch any areas of the product which are causing problems with a view to improving the documentation in that area as well, and overall we understand that the people using the development platform are usually smart, technically minded people, so we ask smart, technical questions of our development team.

The thing is, that’s not really a revelation for me. It’s something we’ve been doing for quite a while now, so much so that I can forget that for a lot of people the term “product documentation” is often seen to be fairly rote task-based, step by step procedures with little in the way of explanation.

Whilst that’s handy when you are still learning a new product, pretty soon that information becomes useless.

Thinking further, the decisions we are making during our current restructure project reflect this thinking as well. One step that was very interesting was asking some of the given audience of our product (our own developers and professional services staff) to do a card sort of some of the topics. They all have a mental model in their heads of how the product (and so the supporting information) is structured. Anything outside of that was a real problem for them to deal with.

It’s that problem area where asking why, and producing supporting information that helps the user understand how something works is far more important than simply telling them which buttons to click.

Since our companies merged we’ve had a lot of discussions and sessions to help the other engineering teams get up to speed with our platform, it’s been a bit of a rude awakening if I’m honest, as there is a lot of knowledge still floating around in the heads of some of our developers.

So it looks like the task next year will be to change that, to make information and the dissemination of it much more a key part of the software engineers thinking. I’m not quite sure how we are going to manage it but I do know that we have to create a new normal where information sharing, product information and an understanding of who is using our product needs to be much more front and centre in our thinking and our working processes.


Comments closed

For the last few months, the team have been rebuilding and restructure our content. We’ve ditched the idea of ‘guides’ for now (although we will revisit those early next year) and after a lot of hard work we are starting to build out new groupings of content. The process has involved a lot of analysis, and we’ve had a few nice little wins on the way, for example; we started using Mindmaps as a way to visualise the content and will be rolling them out as part of our normal planning in the future.

This is the 1000 feet view of what we are building:

And that’s not quite everything…

It’s been a long journey to get to this point, and I admit I have some fear that all of this information is too big to know.

However, we know that the majority of people use search to find content in our system (we publish to WebHelp and host on a developer community website) so I’m confident that with our new structure, which includes a lot more signposting and navigation, the content will be much more usable.

One of the mindset changes was moving away from worrying about product manuals as a construct, it’s very freeing but also quite scary. That said, there has been a lot of work in validating the approach we have taken so we are confident in the approach, even though there has been more work than we originally anticipated (do not under estimate the creation of navigation topics).

Will it work? I think it will, although I’m aware there are likely some gaps that will be exposed that we will need to fill. We will try and plug those as we go along of course, but once this is in place we can start to look at other content. As I mentioned previously, we provide other content types (PreSales overviews of the product, for example) and at some point next year we will go through this exercise on that set of information as well. Thankfully it’s much smaller!


I don’t know about you but I’m getting fed up trying to make everyone realise the value of what we do. Technical Communicators of the world unite!

Why is it so darn hard? Isn’t it obvious? We live in a so-called “information age” after all, so why is it such a struggle to get the message across?

So, for the meantime, I’ve stopped.

My team currently has a separate stream of work looking at how we get better at PR and whilst that runs its course I’ve decided to deploy a different tactic, one which has fallen into my lap. No more will I go cap in hand to department heads, no more will I try to coax, nudge and cajole others into understanding why product information is so important. I won’t roll out the usual reasons, and I will save my “part of the product life-cycle” spiel.

You see, we’ve been receiving requests from different parts of the organisation, based on some work we did in the past. Lots of people are looking for help. At the moment, all of the team are busy but I’m going to pick one of the requests and find a way to get it actioned. That way we will get a quick win and increase our profile a little (it really is great to be part of such a good team, their work speaks for itself) and it should give us an ‘in’, an opportunity to build a relationship with a different part of the business, learn how they work and in time expand what we do as part of our service to them.

Land and expand. Simple really.

At present I know there are many areas of the company producing content. I also know that many of them would benefit from our input, just as I know we don’t currently have the resource and, without a lot of up front research I’m not sure I would be able to guess at what resource would be required to cover the current requirements. Creating the business case to expand operations would take time, and even then a lot of the effort goes into educating people as to why consistent, reliable, re-usable product information is a “good thing”.

With that in mind, getting a foot in the door (landing) before getting involved and agreeing a level of delivery for the future (expanding) seems the most sensible way forward. It allows us to get a feel for where we can best be involved and over time we can increase our influence, and standing, within the company.

Now, where I can buy some ninja costumes?