Author Archives: Sarah Maddox

Tech comm 2015 now on the map

Tech Comm on a Map now displays all the 2015 technical communication conferences that I’ve found so far. Take a look, and let me know if there are any more tech comm conferences, groups, businesses or societies to add.

Tech Comm on a Map puts technical communication titbits onto an interactive map, together with the data and functionality provided by Google Maps. It’s a great way of seeing what we tech writers are up to, around the world. To find out more about the project, or to add something to the map, check out the project information page.

Tech Comm on a Map 2015

Empathy in UX design and development

A new theme is emerging in the UX (user experience) world: Empathy. Putting humanity into technology. Product designers want to ensure they have empathy with the users of their product. We in the tech world want to design for what people need and want, rather than for what’s new and shiny. I think technical writers can contribute to this discussion!

Last month I attended Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. A strong theme emerged at the conference: Empathy, what it means to be human in a digital world, creating an internet for humans… What’s more, this was a spontaneous emergence, not suggested by the conference organisers. It just happened.

My deduction was that this must be a “thing” in the world of web design and development at the moment, whether conscious or unconscious, whether generally known or just beginning to seep into our collective consciousness.

I’m wondering: how many other people have encountered this theme?

Since then, I’ve read a post by Georgina Laidlaw, entitled “Why Don’t You Have a Writer in Your UX Team?” (linked at the end of this post). Georgina was recently at the UX Australia Redux conference in Melbourne, where she noticed a “dearth of writers”. She follows that observation with an excellent and exciting description of the contributions a technical writer can make to a UX team: “five things a great writer knows better than anyone else in the room”. I’ll resist simply listing the five bullet points, because such a bald list wouldn’t do justice to Georgina’s post.

Georgina’s third point struck a chord: “Writers understand empathy“. She says,

Writers deal with emotion all the time. Even the writer of the blender manual is working to avoid frustrating or patronizing you, and to make things seem achievable so that you feel an affinity for the product you’ve bought.

Every professionally written item aims to communicate, and to do that, the writer needs to deal with emotion. They’re skilled at empathising with the target audience — the users of their words — whether that’s on a single-word basis, or a thousand-word basis.

I’d add these points: As technical writers, we focus on analysing our audience, thinking about how our customers work, what they want, and what they need. We get to see early version of the product we’re documenting, whether that be an app, an API, a piece of hardware, or another type of product. We exercise the product as a user would, in order to document its usage. Many of us interact with customers, via feedback on the docs, in forums, or in other ways. We see a different set of customers from those the product managers and marketing/sales teams focus on: we see and think about the “end users” (for want of a better term).

We can chat to the engineers, designers and product managers we work with, to share our insights. We can make ourselves known early in the design phase of a product, again to share our insights and also to expand our own knowledge of the product aims.

So, yes to Georgina and other UX specialists: let’s talk. :)

Here’s a link to Georgina Laidlaw’s post on SitePoint: Why Don’t You Have a Writer in Your UX Team? It’s well worth a read.

These links point to my notes on the four key-note presentations at Web Directions South: InterconnectedAn Internet for Humans too, Being Human in a Digital World, A Voice for Everyone.

A pic from me, for fun:

Empathy in UX design and development

Web Directions 2014 wrapup

This week I attended Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. I’ve blogged about most of the sessions I attended. This post is a summary of my impressions, with links to the more detailed posts.

This was a technical conference for technical folk. Yet the presentations that went down best were those that mixed the human side in with the tech. Those that gave techniques for handling situations and people as well as code. Those that included humour and people in the slides. Code is for people by people.

A theme stood out in the keynote presentations and many of the other sessions: putting humanity into technology. There’s a concern that technical design focuses on what’s cool and new, when it should rather focus on what people need and how users want to interact with their tech.

IMG_20141031_090244 (1)

The quality of the sessions overall was excellent. In particular, Sarah Mei’s presentation on day 1 gave me a lot to think about. Her idea is innovative and unusual: to analyse the way we make technical decisions, so that we can then apply the same process to the harder tech decisions. Jeremiah Lee’s talk on day 2, about what makes an excellent API, had some excellent nuggets of information that were particularly relevant to me as an API technical writer. I especially liked the bit about passive usability testing via analysis of existing data.

My own presentation was on day 1: Bit Rot in the Docs. It was a bit freaky – the sessions took place in a theatre, so I was literally on stage, with bright lights shining down on me and the audience in tiers of seats extending into the blackness.

Looking for more pics? Try Xavier Ho’s photos. There’s even one of me giving my presentation. (I’m in the fourth row of photos, third from the left.)

Here are my detailed notes:

A huge thanks to Maxine Sherrin and John Allsopp for the hard work and dedication they put into organising Web Directions. Thanks also to all the presenters and attendees. It was a great experience! Oh, and one final observation: The chocolate brownies were to die for.

Web Directions 2014 – day 2

This week I’m attending Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. I’m excited to be part of this event. I’ll blog about my take-aways from the sessions I attend, and anything else that comes to mind.

The keynote this morning was Being human in a digital world, by Genevieve Bell. The link is to my post about that funny, inspiring talk. Now for my notes on the rest of the day.

Elements of API excellence, by Jeremiah Lee

Jeremiah Lee is lead API engineer at Fitbit. His talk was about evaluating the maturity of APIs, and what it takes to make an excellent API.

Jeremiah ran through some scenarios that may result in a bad API. For example, you may create an API unintentionally (it was just something we auto-generated, and people started using it), selfishly (we looked only at our own requirements), or blindly (we imitated other APIs, without knowing why).

Instead, we need to actively understand the problem that needs to be solved, and to test it thoroughly before letting it loose in the wild. And we need to design it holistically. How? Tie up with our UX colleagues. We need to understand the people who use the code, as well as the code itself. The users of APIs are our peers – other engineers.

Empathy is an applied science. UX is a research-driven field. The aim is to acquire knowledge, with the purpose of doing something with that knowledge.

An excellent API is functional, reliable, secure, usable and pleasurable. Jeremiah broke down each of those points into smaller divisions. For example, usability breaks down into intuitability, testability, and corrective guidance. Pleasurable means that integrating the API is something you’d choose to do again.

Personas are a useful way of getting to know your users. Remember, in this case the users are other developers. Personas describe the people who use the product and the context they operate in. Personas also make visible our assumptions about users, and give our team a frame of reference. Jeremiah took us through the development of personas for API users, and the type of characteristics we’d need to analyse to create such personas. For example, what technologies are they using, what’s their skill level, and more.

Passive usability testing is the idea that we can use our existing data and systems to test the usability of our APIs. For example, the engineers can examine the support requests with specific questions in mind: at what times are people asking for help – immediately after a release or on long-running software; what are the frequently asked questions; what are the frequently misunderstood concepts; and so on. Another passive usability testing technique is to look at the data about API usage during an integration: how long between app registration and first request; what are the first requests and first errors; and so on.

Then there’s active usability testing. Go out and talk to people who are using the API. Hang out with them at their place of work, and take notes about how they use the API. See how they talk about the API with the rest of their team; how do they get started and what problems do they encounter/solve; how does the API fit in with the rest of their app? Or create a prototype of the API, and have people use it. Jeremiah recommends Silverback to record the user’s reaction, and then look at their emotional responses at various points during the integration. Were they happy or sad, and can we fix the sad moments.

Jeremiah finished by saying he hasn’t given us answers to building an excellent API, because there are no one-fits-all answers. Instead, he has given us the tools to find those answers.

Build better content, by Jonathon Colman

Jonathon Colman is a content strategist at Facebook. I’ve met Jonathon a couple of times, most recently at the STC Summit in Phoenix AZ earlier this year. It turns out we share the habit of waking up before the crack of dawn, and falling asleep soon after the birds stop tweeting for the day. We also share a love of technical writing. :)

Jonathan’s talk focused on how content strategy has to be part of UX strategy. He started off by promising us 127 slides! He’s a “madman with a clicker”. Heh. The slides are at Heh again.

First we looked at some definitions of content strategy. Then we saw some new Facebook content that aim to improve user experience, such as a privacy tool. It’s all about using language as an interface. Language is how we understand things. Content strategy is interaction design, because it focuses on experience, and the users of a product. Content strategy blurs the lines between engineering, design, testing, and so on. It crosses all those silos, focusing on the user. Jonathan calls this “intertwingling”.

The aim is to design content as a system, a product and an experience. Not as a campaign. Jonathan aligns his strategy with Lean principles: build, measure, learn. He also stresses the importance of incorporating your organisation’s core values into the design. And then go back and question your norms and values, especially if something breaks. Always remember that people are on the other end of the system.

“Slow down and fix your shit” – this is the essence of content strategy. Jonathan walked us through the quality framework his team uses at Facebook, and the content principles that guide them through the complex path of designing a product from strategy to the surface where the users see it. Aim for: simple, straightforward and human.

Thanks Jonathon for an information-packed session. Some quotes that made me think:

  • Keep it simple, get to the point, and talk like a person
  • Great content is invisible
  • If you want a better Web, you have to build it

A voice for everyone, by Doug Bowman

Doug Bowman talked about his experiences as Creative Director at Twitter, and how products like Twitter are giving people a voice. If eyes are the window to the soul, then the voice is the gateway to the heart. Whether the voice is spoken or written. A voice can change your day, or alter your life for ever. But a voice can only be powerful if it’s heard.

Doug started working at Twitter five years ago, when there were no designers in the company. So he got to grow the designer team from scratch. He loves Twitter. It’s connected him to so many people that he hadn’t met before.

The message that Doug wants to share is the human connection. Twitter is unique and wonderful because of the people who use it, not because of the service. We can connect with anyone who shares an interest with us, whether we know them or not. We get to overhear the conversations between people we don’t know.

Doug read out some tweets from conference attendees, showing lots of humour and character. He also showed us some cute, funny tweets between people or businesses, famous and not. Where else do you see businesses taking the time to reply to random mentions of their name, and often in the same humorous vein? Then we looked at some more serious tweets among people mourning a loss or going through other difficult experiences.

Tweets are a series of human moments. But you can also analyse the tweets en masse, to see patterns. For example, the tweets mentioning #hungry spike at certain times of the day. How about the tag #tired – it’s the pulse of humanity. You can see when people tend to be happy, late for work, hung over…

Big events show a huge outpouring of emotion, such as when the Giants won the World Series, or shocking world events happen. Doug told us the story of Vivienne, who made a commitment to earn $100,000 to free 500 child slaves, by selling lemonade at a stand on her street for a year. That was 5 years ago, when she was 5 years old. Her father helped her tweet about it. She reached her goal in half the time planned. What’s more, she’s given a TED Talk and runs a company that aims to end child slavery.

These stories of human connection were rooted in Twitter. But Doug’s message is for everything we do. As communicators and designers, we are the creators of the modern age. It’s our responsibility to make sure everyone on this Earth has a voice.

Architecting the rise of connected devices, by Hadi Michael

Hadi Michael is a digital adviser and software engineer at Deloitte Digital. He gave the first of three 15-minute sessions. His talk is about the importance of API layers in the growth of the Internet of Things. An example of a connected device might be a chair. It could have sensors, activators, computational power, and connectivity. The powerful idea is that the devices have contextual awareness. Some devices may decide to activate when you leave the home, such as those that clean the house. Others may switch off when you leave. Cisco estimates that we’ll have 50 billion connected devices by 2020. And that’s a conservative estimate.

How are we going to handle this – how will our solution architectures service this growing number of connected devices? Hadi showed us how various organisations have started preparing. Those that are successful have API layers at the core of their architectures, either unifying their API layer retrospectively, or doing it right from the start. The trick is to move your business systems behind the API layer, at least when there’s any chance that you’ll want to expose those systems to anything other than just the website.

Hadi walked through some tips for designers when taking connected devices into account. Thanks for a tantalising glimpse into the world of connected design!

Welcome to the fold, by Katie Miller

Katie Miller is an OpenShift Developer Advocate at Red Hat. Her presentation, the second 15-minute session, was about higher order functions in JavaScript. Katie started with a story about a secret garden, a chain of paper dolls, and a bowl of pebbles. That was a surprise! The rest of Katie’s talk was about fold, also known as reduce, and how to use it to write elegant JavaScript code. A higher-order function (HOF) is any function that takes another function as a parameter. Famous examples of HOFs are the map and filter functions, which can also be written as a fold.

Be aware also that there is a family of fold functions, such as fold left and fold right. Katie’s slides, with references, are at

Responsive in the wild, by Guy Podjarny

Guy Podjarny is Chief Technology Officer at Akamai. Guy’s talk was about the adoption of responsive web design. Which websites are going response, and how are we architecting them?

When we try to see if a website is responsive, we usually just resize the page and see if the content is cut off. We also look for a scrollbar, which indicates a non-responsive site. This isn’t ideal, but it’s pretty good and we can automate it. Guy showed us the details of the test he ran, and the results. Here are some highlights.

The adoption in the top 10,000 sites has grown by approx 8% over the last year. The average number of requests in responsive websites is substantially lower than non-responsive. The average resource size in the responsive websites is bigger. Interestingly, the image size is also bigger in responsive sites – perhaps because of retina?

Guy also compared responsive designs on the big screen with the small screen. We’d expect a substantially lower volume of data on the small screen. That’s not the pattern that shows up, presumably because the resources are downloaded anyway and then just hidden or shrunk on the client. Only approx 13% of responsive websites are 50%+ smaller on mobile. We’re doing better here than last year, but still need to make an effort.

Mobile-only sites are significantly smaller than responsive sites. Processing time follows the same pattern. Responsive sites take longer to process than mobile sites.

In summary: Adoption of responsive design has nearly doubled in less than a year. But we need to work on the performance.

Haunted machines, by Tobias Revell

Tobias Revell is a critical designer and futurist. He gave the closing keynote of the conference. Note: Today is 31 October. Halloween!

Tobias’s talk revolved around the notion that any sufficiently advanced technology is indistinguishable from magic. (From Arthur C Clarke.) Tobias gave some examples of recent hoaxes: that if you add this app to your phone, it will become waterproof, or that you can put your phone in a microwave oven to recharge it. The amazing thing is that people fell for these hoaxes. But the fact is that people are dealing with such advanced technology that they can’t understand it. As technology gets more and more advanced, it gets more and more opaque.

On the other hand, people have built computers on Minecraft. Some people are even trying to build a computer on Minecraft that you can play Minecraft on. Go figure.

Tobias gave us a link to his site: The Ongoing Collapse, “a growing collection of data sources and links positioned as a reflection of the state of the world in the terms that it likes to use. It’s a gentle ticking of the crumbling weird at the base of civilisation”. (More about the site.)

Tobias ended with this somewhat convoluted, dark thought: As makers of virtual reality, we control people’s perception of objective reality. Happy Halloween!

Thanks Tobias for a rollercoaster ride past ghosts and technologies past, present and future.

Web Directions 2014 – Being human in a digital world

This week I’m attending Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. I’m excited to be part of this event. I’ll blog about my take-aways from the sessions I attend, and anything else that comes to mind.

Genevieve Bell is director of User Experience Research at Intel Corporation, and vice president of Intel Labs. She gave the keynote on day 2 of the conference: “Being human in a digital world”. Her focus was what makes us human and the intersection of tech and culture. Below are my take-aways from this funny, engaging, thought-provoking talk.

Genevieve told us about her childhood in the Northern Territories, where she lived amongst indigenous people who would take her out into the bush at the drop of a hat. She often spent time in the bush learning from the people instead of attending school. This has shaped the way she views the world. Next, Genevieve led us through a rollicking tale of how she got her job at Intel. It’s well worth hearing. When you have the chance, sit her down, give her coffee, and ask her about it.

Genevieve’s role could be summarised like this: How do you make sense of what people care about, and how do you use that to shape next-generation technology? It involves telling stories about the future. We saw some stories from the 50s about what the future may be. (This has been a theme of the  conference keynote presentations.) Some of them were eerily close to the truth. Genevieve said that the stories show us what people’s aspirations are.

People need friends and family. The technology that makes use of this fact, such as telephony, as the ones that have succeeded. The ones that help people connect with other people. Facebook, Instagram, and so on. We also want to belong to community of people who share our skills, interests, or values. Technologies play into this too. Pinterest, Tumblr, eBay. We need to belong to something bigger than ourselves. Viz the Arab Spring. We use things to tell the world about ourselves: clothes, cars, and technology – what do you own, what services do you use, and what worlds do you belong to. And lastly, we need to keep secrets and tell lies. Evidently the average human being tells between 6 to 200 lies a day! Sharing secrets with just one or a few people is a way of bonding.

We worry what people think about us. So, we filter what we tell other people and what we put on the Internet. Are smart objects such as bathroom scales and fridges going to gossip about us? There are of course also genuine concerns about the amount of data that is available about us now. But the notion of new technology revealing information about us isn’t new. Genevieve told how, when electricity was about to be introduced to homes, gainsayers said it would make people vulnerable because strangers would be able to see what they were doing in their houses at night.

It turns out that people need to be bored. It puts our brains into a different state, where creativity can happen. But we’re living in a world where algorithms generate content that we should like. We’ll go with that for a while, because we like the familiar. Then we’ll get bored, and want to be surprised.

Genevieve says there’s something unnerving about living in a world that knows how to entertain us. The notion that once in a while, your device might do something different and surprise you, is one worth contemplating. Genevieve gave the example of a device that wakes you up with your favourite coffee every morning, then one morning suggests you look at a particular piece of art before having the coffee.

Is the Internet making us more uniform, more global, or more different? People want to be different. We want to retain our cultural identity. We spend a lot of effort maintaining our boundaries, and we imagine technology will help us do that. Even the “Internet” is now split into different internets in different parts of the world.

People want to feel the passage of time, and to have periods that are distinguished from other periods. Genevieve thinks this is a space worth investigating, particularly in connection to our smart devices and digital technology. How can we manage them, in their always-on state? We also want to be able to reinvent ourselves, which means we may want to be forgotten.

So, where does that leave us? There are things that make us human, that don’t change or only change very slowly. There are parts of us that have been in flux for ever. Genevieve showed two columns, “stable” and “in flux”, with five aspects of humanity in each column: friends and family, shared interest, reputation, and so on. The technology that plays to one of the stable aspects of humanity will endure. And the side of us that is in flux is where there is space for flashes of brilliance. This is where we can do extraordinary work.

Thanks Genevieve for a funny and idea-generating talk.


Get every new post delivered to your Inbox.

Join 1,577 other followers

%d bloggers like this: