Just a “normal” day in my life as a Technical Writer

The only usual thing about my days as a Technical Writer, is that it’s rarely usual. Today was no exception.

I manage the technical writing function, including another member of staff. Unfortunately for me, they started a week’s holiday today and I’ve just returned from two weeks away. The timing of our holidays isn’t ideal, but I’d monitored what was going on during my absence. I didn’t actually do much, but it ensured there weren’t any unpleasant surprises on my return.

My journey to work involves a 15 minute walk to the station, a train into central London, and a further 20-25 minute walk. I could get a bus or tube, but I figure that by the time I walked to the bus / tube, waited for said bus / tube to arrive, decide not to force myself onto an already crammed bus / tube, get on the next bus / tube, and walk to the office, I may as well just walk. Besides I enjoy walking.

Today I set off wearing a fleece, and soon regretted doing so. After the walk to the local station, it came off and never came close to being worn again. It was announced today that the UK had just experienced its joint hottest summer on record. The last week or two had seen a slight drop in temperatures and plenty of rain, but today demonstrated that whilst we are now in the meteorological autumn, it’s still warm enough for a short sleeved shirt commute.

Taking of surprises, whilst I was away, a desk move was announced. I knew this was happening, but unsure when. Whilst I was away it was announced it would be taking place on the Friday before my return. I’d asked my team member to ensure everything necessary was moved. This happened, but of course on arriving this morning I spent an hour ensuring everything was setup to my desired configuration.

A colleague last week had sent me a meeting request for 11am to discuss a forthcoming release. We’d completed all the updates some months ago, but the release was delayed. With the release imminent, she wanted to discuss some finer detail of what we’d provided. I went in search of her, not easy as she’d moved desks also, and managed to get the meeting moved to the afternoon. Enough time to organise myself and start trawling through my emails.

Within 30 minutes, I’d been approached by three separate Product Managers to inform me of projects in the pipeline. Only one of them is in any way urgent, likely to be released later this month. It doesn’t contain too much additional functionality, but annoyingly does contain new icons. I made a note to inform our Education Team who produce our certified video training programmes. They just love having to update all their videos every time an icon changes! We’ve got another large project completing about the same time that we’d both been working on. I may have to look at reallocating resources to ensure both project deadlines are met, once I’ve evaluated the effort involved. That’s not for today, so an item is added to my to do list.

Up to lunch was spent on admin. As a manager, admin is an essential part of what I do. It may sound boring, but having processes and ensuring they’re followed is pivotal to ensure a smooth running team. Running reports, trawling through my Inbox to prioritise any work items, or updating our project spreadsheets with details of changes / timescales, these tasks have to be done.

Around 12:30 I down tools for a trip to the gym in the basement of our office. I’m a keen runner, but have been recovering from a serious injury since late March. Today was my first day back on the treadmill, so I planned a gentle 30 minute jog. I want to get back to doing my local Parkrun ASAP. Being a Parkrun volunteer is fun, but just doesn’t give you to same buzz. I’m not looking to get back to anything like my PB just yet, but I’ve a goal in mind.

Back in the office, and I’ve time to eat a sandwich and apple before my Rescheduled meeting. The Product Manager and I discussed some minor changes to our best practice guides. A perfect chance to do some actual technical writing. As we discussed each setting, I changed the pages on the fly.

Afterwards I finished going through my Inbox. That only left the automated emails, comments generated by users, and those sent to our team’s distribution list, each of which is sent to a separate folder. The comments were easy, as not all are related to our Knowledge Base.

By mid afternoon, my earlier plea to my colleagues to come and eat a biscuit or two I’d brought back from my holiday, seemed to having some affect. The biscuit mountain was reducing, but not enough to avoid me taking the easy route to solving the issue of having the afternoon munchies.

Late in the day and another work request came my way. Four new projects in a day. That’s a record! Once again I update our project spreadsheet with the details. It’s a useful shared resource that the team and my boss can use to see what is coming up.

As folk began to leave for home, I pondered whether to stay late and finish off those unread automated emails. I consider logging on from home this evening rather than staying in the office. As a global company, and with my manager not being based in the Uk, I’m used to occasionally working irregular hours. However as today was a US holiday, I decided I’d have some time tomorrow morning to sort those email folders out before the USA woke up.

So it was a walk to the station, sans fleece. An unusually busy train meant a less comfortable journey than normal. My wife texted me to say she’d bought some milk and bananas, so I didn’t need to visit the supermarket on my way home. Bless her, as I hate that supermarket with a passion. It’s very handy for commuters as it’s only a minute from the station, but it’s layout and poor customer service makes a visit a soul destroying experience.

Home by 7:30, I change into shorts and sandals, take the bins out for the bin men who arrive early tomorrow, and sit down to eat. Nothing fancy tonight, but that’s OK. Plain food can still be tasty.

After catching up with my wife on her day at work, I spend time catching up on what’s been going on online. I normally try to do this during my train journeys, but today I didn’t. I predominately use Twitter for professional information, and Facebook for personal stuff. After a few minutes trawling, I had the idea for this post, but before I started, I prepared my lunch for tomorrow.

As my bed beckoned, my mind turned to what I can expect tomorrow. I know what I’ve left from today, but you can bet there’ll be the odd curve ball thrown in to make life interesting. Working for a software company in a dynamic environment is never boring.

Technical Communicators: There’s hope for us yet!

“I found that exercise rather depressing”, I said having participated in an exercise at a recent training session. Unsurprisingly my slightly tongue-in-cheek comment solicited a question from the trainer. “Why’s that?” To answer that, I need to explain the exercise.

We were given a scenario. We’re in a large city with a transport problem. There isn’t enough of it for those who want to travel. The answer is possibly hot air balloons! As the Head of Transportation, we’d one hour to research whether they really are the answer to all your problems. In order to do this, we had four options:

  1. Read the blueprints and instruction booklet?
  2. Watch other hot air balloonists and devise a plan?
  3. Meet with a subject matter expert and ask them questions?
  4. Just buy a balloon and try it out our self?

In our group only I went for option 1. Five went for option 2, with one other going for options 3 and 4.

Now do you see why I said what I said? As a Technical Communicator, I design how best to present the blueprint, and I write the instruction booklet. If no one but me would choose to even look at them if they’re in a hurry, what is the point in my profession?

OK so we’ve managed to buy another hour’s research time. What other research method of the three remaining choices would you choose? Six went for option 3, with one each for options 1 and 2.learning_styles

With eight people, it’s hardly a scientific sample, but it did raise some interesting insights into the different learning styles people have. According to Peter Honey and Alan Mumford, these are:

  • Option 1 = Theorist
  • Option 2 = Reflector
  • Option 3 = Pragmatist
  • Option 4 = Activist

As a follow up exercise, our group completed a questionnaire that aimed to demonstrate which of the four learning styles we best fitted. Guess what? The person who’d said they’d immediately just buy a balloon and learn from their mistakes, found they’d actually a high theorist score.

Ha! You can deny it as much as you like, but well designed and written technical documentation will always be needed. Especially for those who say they don’t read it.

Mimecast & Ataata: A TechComm match made in heaven

Today Mimecast announced it had bought Ataata, a cyber security training company. It’s a common sense acquisition for one of the leading cyber security companies, but from a technical communication perspective, it’s so much more.

Ataata provides short videos aimed at educating users about all aspects of cyber security. There’s lots of training companies who provide educational videos, but Ataata do so in a way that’s engaging and fun. Users love them. In fact they look forward to receiving the next one! Take a look at one and see for yourself.

Mimecast has been looking at how it can educate its users. We recognize that having the means to prevent threats from entering an organisation is only part of the solution. If you personally don’t fully engage in identifying where threats exist, you’re asking for trouble. In short, the weakest link is you.

I’ve been involved in projects at Mimecast looking at educating users about cyber security. We’ve embedded copy into the user interface to warn them about phishing attacks, and written white papers on steps companies can take to protect their data. It’s not just about using our cloud solution. This has been a focus of our CEO, Peter Bauer who’s been quoted as saying, “Our customers desperately need help training their human firewalls.”

It’s as a technical communicator that I’m interested in the Ataata acquisition. Our job is helping our users use our software, but achieving this is so much more than providing help. Mimecast recognizes the need to provide assistance where it’s needed most. Yes we provide online help, but we also provide embedded user assistance in the user interface.

This takes the form of text and video tutorials, but we’re also redesigning our user interfaces from the ground up. Gone are the dialogs with 20-30 fields and options, and in come wizard type dialogs with user friendly questions. By answering a few questions, we can identify the configuration a user needs, and set the options for them behind the scenes.

All this is designed to deflect support calls. Support calls cost money. End users spend time looking for content, and if they can’t find or understand the content, they contact our support staff. Whether it’s the cost to our users trying to complete a task, or our support staff dealing with queries, time is money. If we can prevent our users ringing us, it’s a win win solution.

This acquisition may not directly educate users in how to use our software, but the preemptive nature of Ataata’s solution means users should have less issues. The most expensive support call category involves data loss. Phishing, whaling, and impersonation attacks can take time (a lot of it) to recover from. Our software has solutions to prevent these attacks, but we want to provide another layer of protection.

In the ideal world, our cyber security solutions should never be needed. If we’re all vigilant 100% of the time, companies like ours wouldn’t be needed. The fact that companies like ours exist, shows how delusional that view is. Having a multi faceted approach to protecting your data is the way ahead, and from a technical communication perspective there’s so much scope to integrate our content in a fun and engaging way.

Choosing the “right” CMS

I’ve spent a couple of hours looking through the wish list items added by users of a well known CMS. What stands out, is how users want more from their CMS. Whereby in days gone by they were happy with a simple editor that allowed them to capture content, now they want (to name just a few trends):

  • A richer editing experience (e.g. indented list items, image / video, and table formatting).
  • The ability to import / export from / to more file formats.
  • Reusable content (e.g. variables and text snippets).
  • Smoother workflows for editing, reviewing, and publishing content.

What strikes me about this list, is how all of these could be achieved with one of the specialist technical writing applications. This begs the question why more content curators aren’t using them.

There’s no simple answer to this. It depends on the requirements and culture of the organisation. Maybe it’s a need to keep all the content in one place, or maybe it is ignorance of what a specialist technical writing application offers.

Whatever the reasons are for mot using one tool or another, there is one question everyone looking at CMS providers needs to ask. And it isn’t, “Can tool a do x, y, and z?”

The classic mistake many make, is to focus on the technology before considering the requirements. To use a slightly crude analogy, there’s little point in buying a family friendly Hyundai saloon car, and then wondering if it is the right car for a trip across the Sahara desert. Instead you should consider what you’d need by way of four wheel drive, storage for water / fuel, and the ability to pull yourself out of a sand dune. Once you’ve done that, then (and only then) you can look around at the vehicles best suited to your needs.

There are a variety of methods to ascertain if a CMS meets your needs. For example:

  • Search the product’s user forums.
  • Look for online user groups, particularly those not controlled by the vendor.
  • Look for wish list items to see what users are wanting that isn’t currently delivered.
  • Attend user group meetings or conferences.
  • Ask your peers.

If after all this you find yourself in a situation where you must host the content in a particular CMS, don’t be fooled into thinking you must author it there too. Look into the CMS’s import / export functionality. Even if this isn’t there out of the box, perhaps there’s an API that can help. Admittedly this normally requires additional resource from elsewhere in your organisation, but if the major stakeholders have the organization’s interest at heart, that shouldn’t be a problem.

Choosing a solution for your content curation needs isn’t easy, but an quick easy decision could prove disastrous and lead to a repeat of the exercise further down the line.

Adobe’s Technical Writing Trends 2017 Survey Results

Each year Adobe run a survey for Technical Writers. It asks questions about the tools, methodologies, and strategies used by those in the technical documentation industry, and tries to predict what will change in the future. They have a vested interest in the survey’s results, as they produce a number of applications used by Technical Writers. That said the results aren’t focused on their products, inside aiming to provide an honest picture of the industry. Having listened to the survey results in their recent webinar, here are my key takeaways.

Structured Authoring

It isn’t a surprise to see companies increasingly using structured authoring. It has many benefits, particularly for those with large content silos, multi-faceted output requirements, or translation needs. As such, the mean requirements for moving to a structured authoring environment were the ability to reuse content, apply consistency, and make it easy to update.

What is a surprise is the growth rate. According to this and past surveys, companies that have either adopted or were thinking or adopting structured authoring, has grown from 20% in 2012, to 50% in 2017. Predictably it is the companies with a 1000+ workforce that use structured authoring most, with over 50% of them adopting the methodology.

Benefits of structured authoring

DITA XML remains the stand out standard used to deliver structured content, with nearly 75% of structured authoring respondents either using it or likely to use it. Custom XML solutions come second with 47%. Again no real surprise, apart from the percentage of those focused on DITA XML. It has been around since 2001, but in recent years has been widely developed and adopted since IBM handed over the management to OASIS.

Output Types

PDFs are dead. Long live PDFs! Folk have been predicted the demise of PDFs to deliver content for years, but they’re still widely used. The survey shows a 90% dominance over all other output types. Responsive HTML5 comes a distant second at around 50%, although this is up significantly on recent years. That said, it looks like PDFs will be around for awhile yet. Not surprising really when you consider their advantages, and the lack of anything that even remotely matches their functionality.

Output Types

One interesting side discussion around PDFs was their lack of responsiveness. As we deliver content on a variety of devices, the need to make content usable on each and every device without having to create and maintain separate source files, is of paramount importance. The rise in usage of responsive HTML5 is testimony to this. Adobe more or less dodged the discussion on whether PDFs would be made more responsive. To be fair to Adobe, there wasn’t a great rallying cry from us users to make them responsive.

Personally I think most of us don’t even try to use PDFs where there’s a responsive requirement. We prefer to use a different output type that best fits our requirements. If we want responsive output that works on a tablet or mobile, are PDFs really the best output format? They can take up considerable storage space, and aren’t as user friendly as other delivery methods.

Other Usages

The later part of the webinar focused on a couple of areas that raised an eyebrow:


There are a small number of survey respondents using a chatbot to deliver technical content to users. It is fair to say that such delivery methods are still in their infancy, with many differing styles being used. It is also unclear how the tools we use to deliver content fit in with this delivery methodology. If this delivery model becomes more of a requirement, perhaps our tools will have to change accordingly.

I’m less sure of the need for our tools to provide chatbot functionality. There are already a number of applications that provide this. What is needed is a way to leverage our technical content inside these applications.

Alignment of Marketing and Technical Content

With the rise of structure content usage, I can see why the synergy between marketing and technical content has increased. If you can reuse content for multiple needs from a single set of source files, that’s a big vote winner. However it requires a real sea change in a company. Most companies I’ve worked for have an ongoing battle between the Marketing and Technical Communication departments. We both see the need for content reuse, style, and consistency, but have very different ways of achieving it. Part of the reason for this has been the tools we use to create the content. However if you move to structured content, the tools become less of an issue.

Adobe have a vested interest in getting more folk in an organisation to use their software. The trouble is their user base has historically been the Technical Writer community. With the growth of content marketing, it is natural that they see this as an opportunity to expand their user base. So far, I’d say this has only had limited success, but this is a long term strategy.


The results of the 2017 survey may not have provided any real surprises, but had enough of interest to make me sit up and take notice. The few thousand respondents provided a representative sample of our community, and covered a large number of job functions and levels of seniority.

The BBC and their Trump localization challenge

Warning: This post includes language some may find offensive.

german_swearwordPresident Trump’s recent undiplomatic language to describe Africa, Haiti, and El Salvador was a big news story. So how did the BBC report it? That depends on where you were watching or listening.

Whilst the word “shithole”was deemed acceptable to a domestic audience in the UK, it wasn’t to folk in the US. You see The BBC is bound by the guidelines issued by the US Federal Communications Commission (FCC), that regulates TV, radio, cable and satellite output. It lists words that are deemed offensive or indecent.

The end result was that listeners to BBC Radio 4’s Today programme were able to hear the quote in full, whilst those watching the BBC’s World Service received a slightly different quote.

In fact it left reporters with a bigger question. Could they report the story at all? If they couldn’t use the word “shithole”, what word could they use to get past the FCC’s regulation? “Arsehole” was deemed inaccurate, so should you use a nondescript phrase instead (e.g. “Trump’s vulgar slur”). The trouble with that is the story loses potency.

Localization of any kind is a sensitive issue. I mean why do you think the Red Cross is rebranded the Red Cresent in Islamic countries? It is so easy to offend.

So what would you report Trump’s quote? I think I’d have just translated it into German. It sounds so much better.

Is this technology for technology’s sake?

virt_assistA BBC News page caught my eye today. It focuses in on the battle between Google and Amazon for the virtual assistant ground.

Reading through the page, one question comes to mind. Is some of the technology innovation displayed at the CES 2018 Conference really necessary?

One use case mentioned in the piece is Amazon’s Alexa being fitted to a bathroom mirror, and then being able to turn on your sink tap or flush your lavatory. Another is Google Assistant being fitted to car entertainment systems.

Here’s my beef with virtual assistants. They’re really not solving the big problems.

OK I know of some people who’d die for the ability to flush a public lavatory without touching anything the great unwashed have touched before. But if you have to, is it really that big a problem?

The in car entertainment system has a practical use at least. I can see a use case for playing your favorite track without fumbling for a button on the display and taking your eye off the road.

The virtual assistant marketing makes a point that you can switch on the oven to cook your dinner 30 minutes before you arrive home. You can even tell delivery men that you’re not at home and to leave what they’re delivering in your back yard.

Useful? Perhaps, but both of these use cases have flaws.

I won’t leave any electric or gas device (except the TV or  lights) switched on whilst I’m out of the house. Having a cooking device come on just seems unsafe to me. Likewise I’m really uncomfortable with telling people I don’t know that the house is empty. I mean what if they broke in and stole all my tech? What would my Amazon Alexa or Google Assistant control then?

To do lists: I love (and need) them :-)

OK I admit it. I’m a bit of a stickler for detail. Oh and I hate mess. The end result drives my wife mad. Minimalism rules as far as I’m concerned, and that goes for my whole life. Whilst others may rely on pure brainpower to remember to do things, my to do list is online. There’s no scruffy scraps of paper littering my desk.

My Todoist productivity report
My Todoist productivity report

My tool of choice is Todoist. It’s an easy to use to do list app, that has some useful organisational functionality. Some of them are even available in the free version. I use the premium version, which at less than £3 a month is a steal. Among the most useful benefits for me are:

  • Adding taxonomy by adding labels to tasks.
  • Adding comments and file attachments.
  • Creating custom task filters to focus on important tasks.
  • Creating tasks directly from my email client.
  • Synchronizing my task list across multiple devices.

Anyway, enough of the sales pitch. What I wanted to share was Todoist’s statistical analysis of my 2017 productivity.

They sent my a report that is pure nectar for someone like me. It’s full of detail of how many tasks I’ve completed, what days and times of the day I’m most productive, and even the days I postpone or reschedule tasks the most. Yes even someone as organised as me (ha!) can run out of time to do  everything I want.

I won’t bore you with the report’s detail, but the end result of all the backslapping is that I’m among the top 1% of Todoist users in 2017. The exact number of Todoist users seems to be a closely guarded secret, but a smart guess is in the millions.  So if there are two million users, I’m among the top 20,000 for productivity.

Perhaps I need to start recording my productivity. Oh and add a recurring task in Todoist to remind myself to do it 🙂

Is your communication technique effective?

If you work in an office, you’ve multiple communication methods available to you. Whether it is a telephone, email, an Instant Messaging (IM) application, or face to face. Whatever you have available, knowing when to use each one is a skill worth learning.

The trouble is, that’s easier said than done. A lot depends on your office environment and traditions. I find it helps to answer a few simple questions before taking the leap.

Location! Location! Location!

If the person you want to communicate with is located two desks from you, it can be more effective to just speak to them. If it is urgent, you should say so, and give them some background information in order for them to make an informed decision about whether it is OK to interrupt them. Just because you have interrupted them, doesn’t make it the best time for them. Perhaps start with, “Can you spare me some time to discuss …..”. If they can help, they should be willing to accommodate. If they can’t, you can agree a time when they can.

If they’re not located nearby but in the same office location, you can still adopt this approach. It’s good to get out of your seat and walk around occasionally too. Of course a lot depends on time management. If every time you needed something you walked to the lift and took it to the 10th floor to speak to someone, you’ve questions to ask yourself about your time management.

Things get more complicated still with larger firms. For example I lead a team based in London, but with a manager based in the USA. I deal with individuals on a daily basis spread across different time zones. Getting information from someone who’s still asleep or out for the evening is near impossible. This is where the next question arises.

Everything is urgent, right?

In today’s modern competitive world, corporate environments often see results as the major success factor. This is true in some roles, but mostly it isn’t. Knowing the urgency of the communication, and what you expect someone to do something for you, is key here.

If it really is urgent and the person you want to communicate isn’t free, what then? Could you wait until they are free? Could someone else help who is available? Only if the answer to both these questions is a definitive “No” should you continue.

Even if you think it is urgent, a second opinion can prove invaluable. You may absolutely need some information to make your target of getting a task complete by this Friday, but if you don’t complete it until Monday would the overall project fail? It is rare for deadlines to be definitively set in stone that there isn’t some flexibility. Go and talk to someone.

What’s the objective?

Finally understanding why you need to communicate with them in the first place is important. Ask yourself all the following questions, not just one:

  • Is it to get information, or provide it?
  • Do you need to communicating with one or multiple people?
  • Do you need to share some information live with them (e.g. presentations, demos)?
  • Where are they located?

Having the answers to these will help you understand the best communication method.

My Pet Hates

Before I sign off, here are a few of my communication pet hates:

  • Don’t email me and a minute later come over and ask me why I haven’t responded. If you need an urgent response, email isn’t the way to go.
  • Don’t assume that just because you need to respond to a communication, that everyone else who received it needs to receive your response. If I receive a message sent to 20 people informing me of someone’s promotion (i.e. useful information) I don’t want to receive 19 responses offering personal congratulations to that individual (i.e. not at all useful).
  • Don’t substitute an IM application for email. This is perhaps more of a generational issue, but younger folk are used to getting instant responses. It’s the social media effect, but in an office environment it doesn’t always work. IM applications can be useful, but they aren’t an email alternative.
  • Companies with more than one IM application. If that is you, don’t spam them all. Think about which one the recipient is likely to use. If you don’t know, use face to face and ask them for next time.
  • Don’t use email or instant messaging to have a discussion. Sometimes what starts off as a simple question sent to multiple recipients snowballs into a discussion with an ever increasing recipient list. Stop right there. Organize a meeting or conference call with the key recipients, and agree a way forward.


This post deliberately doesn’t try to tell you to use a specific communication tool. There is no hard and fast rule. It gets you to step back and calculate the most effective tool to meet your objective. Oh and remember, what met your requirements this morning, may not be suitable this afternoon.