Tag Archives: Documentation

Is GraphQL really “self-documenting”?

If you Google for ‘API trends’ or ‘the future of APIs’ , one technology that crops up a lot is GraphQL. Developers rave about it being a more powerful and flexible alternative to REST. Not only that but if you’re a technical writer like me, claims that it is self-documenting are particularly interesting. So what is GraphQL and is it really as self-documenting as people say?

What is GraphQL?

GraphQL is an open source data query and manipulation language that was developed internally by Facebook for their mobile applications before being released publicly in 2015. Since then it has grown in popularity with some people claiming it might replace REST APIs in the future.

Like REST APIs, both operate over HTTP with requests being sent to retrieve or manipulate data. The key difference is with REST you might need to send requests to multiple endpoints to retrieve a particular set of data, with GraphQL there is only one endpoint so with a single request you can retrieve an object and all of its related objects.

For example, with this GraphQL schema and server wrapping the SWAPI (Star Wars API), you can retrieve multiple pieces of data using just one endpoint. In this case, finding out the species and home planet of Luke Skywalker by adding more fields to the endpoint:

Star-Wars-GraphQL

“The self-descriptive nature of GraphQL”

There seems to be plenty of love for GraphQL on Twitter with developers praising its speed, flexibility and introspective nature. The other key attribute that crops up a lot is “self-documenting” or “self-descriptive”:

One developer even went as far to say that GraphQL doesn’t require documentation at all. However, after playing around with GraphQL and experimenting with some public GraphQL examples out there, I’m not so sure I agree.

Naming matters

The key thing about GraphQL from a documentation perspective is the importance of naming. Lee Byron, one of developers behind GraphQL, spoke about this in his talk “Lessons from Four Years of GraphQL” at the GraphQL Summit in November 2016: “Naming things is super important in GraphQL APIs,” he said. “An important question to ask when designing APIs is ‘Would a new engineer understand this?'[… ] And that means no code names or server-side lingo.”

Lee-Byron
Lee Byron, one of the developers behind GraphQL, spoke about the importance of naming.

He continued: “Imagine that most of the engineers who are going to be using your API might not find it so easy to go and find out how that field maps to some underlying system. It’s really important not just to have names that are good but to have names that are self-documenting. Naming things that adhere closely to what those things actually do is really important to make this experience actually work.”

“An important question to ask when designing APIs is ‘Would a new engineer understand this?’ […] Naming things that adhere closely to what those things actually do is really important to make this experience actually work.” – Lee Byron

Despite Byron’s warnings, fields with poor or no descriptions were a common issue in the different GraphQL APIs I looked at. In the example below, taken from the GraphiQL documentation explorer, I had no idea what the ‘section’ query field did or what data it sent back because it had no description:

Screen Shot 2018-07-25 at 18.44.37

Apart from the documentation explorer, another way to see what query and mutation fields are available is the auto-populating feature in GraphiQL. Hovering over the field or type reveals a description but this can be as useless as the description in the documentation explorer if all it says is ‘Self descriptive’, as this Twitter user found out:

Does GraphQL need documentation?

I agree that GraphQL is self-descriptive and if you’re familiar with the query language and the schema, its introspective nature means it is easy to refer to the description of a field or type to find out what it does. One of the other advantages of GraphQL is the API documentation is easy to keep accurate and up-to-date as the descriptions are pulled directly from the code. In version 0.7 or above of GraphQL, this is as simple as adding a comments directly above the type or field in the code:

Star-Wars

However, GraphQL is only “self-documenting” if the developer or a technical writer has given the fields adequately intuitive or self-descriptive names or has added decent descriptions for them in the schema code. If the names are obscure or the descriptions aren’t great then your GraphQL API is as useful as a chocolate teapot and there are already a few chocolate teapots out there from what I’ve seen. So I guess the good news for technical writers is that we still have a role to play in helping to document GraphQL, it isn’t a magical solution that renders us unnecessary just yet!

Advertisements

The Story behind Slate: An Interview with Robert Lord

Back in 2013, developer Robert Lord, then an 18-year-old intern at Tripit travel software company, was challenged to create an API documentation tool by his boss. It took him several weeks but the result was a beautiful, responsive API documentation generator called Slate. Five years later, it has grown into a popular open-source tool that is used by a number of global organisations and companies including NASA, IBM and Coinbase.

cover-image-for-above-the-entire-post
Robert Lord created Slate while interning at Tripit. Copyright© Concur Technologies,

Lord said the Slate project grew out of a set of requirements the Tripit engineering team had at the time. He said: “I was interning at TripIt and my boss pointed me towards some two-column documentation pages and said ‘We’d like a page like this for our new API.’ They also had the requirement that their technical writer could make changes, and I think they didn’t want to write raw HTML. I made a generator that ended up being pretty generic to any documentation, and convinced them to let me open source it.”

How to Use Slate

Slate is simple to use, you fork the Slate Github repository and create a clone. Next you customise the code to meet your requirements; adding a custom logo, fonts and any additional CSS styling in the source folders, before adding your API endpoints and their descriptions in Markdown.

screenshot-slate
Slate helps users to create beautiful, intelligent and responsive API documentation.

When you’re done, you start Slate and launch your API documentation site using Vagrant or create an image using Docker. The result is an attractive, responsive three-panelled API documentation site with code samples in multiple languages down one side and a smooth scrolling table of contents down the other. For more information on how to use Slate, follow the instructions in the Slate README.

Slate in the Wild

Today more than 90 people have contributed to Slate on Github, it has been forked more than 13,000 times and has been given more than 23,000 stars. Some of the organisations and companies listed as users include NASA, IBM, Sony, Monzo, Skyscanner and Coinbase. There is a list of more than 90 companies that have used it on the Slate in the Wild sub-page of the repository.

This slideshow requires JavaScript.

Lord admits he still finds it “pretty surreal” that such large companies have adopted what he labels the “buggy project” he created as a teenager. “I really did not expect anybody else to see it or care about it,” he said. “Slate never really had a big rush of new users all at once, the growth in stars has been more or less linear over the years. No hockey sticks here. So there was never a single moment where suddenly a bunch of people were using it, it was a very slow process of discovering one company at a time.”

Life after Slate

Interestingly, a year after working at Tripit, Lord interned at Stripe, one of the leading API-first companies whose own API documentation inspired him when creating Slate. Stripe realised the value of their product hinged on people being able to read and digest their APIs. They invested a lot of time and effort in developing their own in-house API documentation tool and set the bar for the rest of the industry with the two-panelled design that has inspired so many other API tools.

Lord had plans to develop further API tools but decided to focus on other things. “Initially had some plans for similar tools,” he said. “But I think I realized I’m still early in my career, and would rather branch out and work on a variety of projects instead of focusing in on just one area.” Despite moving onto other projects and being fairly modest about the success of Slate, it’s an impressive piece of work for the young developer to put on his resumé. Indeed, one of the main reasons he asked Tripit to allow him to open source the project was so he could show future employers his work. “I mostly convinced them to open source it just so I could point future employers to this chunk of code I wrote,” he said. One company clearly took notice, Lord starts work on Fuschia at Google in a few of weeks time.

Write the Docs Portland 2018

Earlier this year I stumbled upon Write the Docs, a global community of people who care about documentation, and through its Slack channel, I have learned so much from the advice and knowledge shared by its thousands of members. The discovery has been a real godsend for someone like me who has worked independently or in small teams for most of my technical writing career.

This month I was lucky enough to go halfway across the world to the annual Write the Docs conference in Portland, Oregon to meet some of the community in person and listen to some brilliantly insightful and entertaining talks from fellow technical writers. In this post, I’ll share my highlights of the conference, my favourite bits of Portland and offer some advice on how to get there.

Conference Highlights

DISCLAIMER: I didn’t attend every single presentation but all of the talks I listened to were great. I’ve highlighted a few memorable ones below:

Kat King from Twilio, who had the unenviable task of giving the first talk of the conference, delivered an entertaining and engaging talk about how she and her team were able to quantify and improve their documentation with user feedback.

Beth Aitman from Improbable spoke about how to encourage other members of your development team to contribute to the documentation. This is something I think we all struggle with and can relate to. It’s well worth a watch:

Bob Watson gave a great talk about strategic API documentation planning, with some interesting tips about your target audience and the different types of API doc consumer  you might come across. These included the ‘Copy and Pasters’ and the ‘Bigfoot’, the rare developer who actually studies the documentation and applies the code!

As well as the main talks, there were some excellent Lightning Talks, five minute presentations given during the lunch breaks, that contained some real gems such as Mo Nishiyama’s resilience tips when dealing with Imposter Syndrome and Kayce Basque’s talk on improving response rates from feedback widgets:

If the talks aren’t your thing, there was also an Unconference where you could discuss topics such as API documentation, documentation testing, individual tools; whatever you want really. I just sat and talked with two technical writers about a documentation tool for half an hour!

Apart from the people, one of the best things about Write the Docs Portland was the venue, a striking 100-year-old ballroom with a “floating” dance floor that has played host to the likes of Jimi Hendrix, the Grateful Dead, Buffalo Springfield and James Brown. Also, if stickers are your thing then you could collect a load of stickers provided by the conference sponsors, hiring companies and Write the Docs themselves (see below):

Portland Highlights

Apart from its scenic surroundings and the views of the Tualatin Mountains, Portland has a lot to offer in the city itself. Some of my personal highlights included:

Doughnuts – Portland has a reputation for great doughnuts. We skipped the enormous queues outside Voodoo Doughnuts and went to Blue Star Donuts instead. The PB  & J with habanero pepper was pretty unusual!

Coffee – Portland has developed a thriving yet relaxed coffee culture with more than 30 coffee roasters across the city. It goes without saying that the coffee here is good! Check out Heart or Barista.

Restaurants – The food in Portland was amazing. One of my favourite meals was at Life Aquatic-themed oyster bar Jacqueline in SE Portland. For sushi check out Masu on SW 13th Ave and for a relatively cheap but delicious lunch go to Nong’s Khao Man Gai thai food cart.

Washington Park – If you want to escape the sights and sounds, head to the 412-acre Washington Park which boasts a Japanese garden, a zoo, a rose garden, an amphitheatre and lots of trees!

Powell’s Books – No trip to Portland is complete without visiting the world’s largest independent bookstore. My only advice would be to pick up a map and have some idea of what you’re looking for, otherwise you’ll find yourself wandering the many colour-coded sections and aisles for hours.

How to get there

If you live in the US or Canada, it might be slightly easier to convince your boss to fund your trip to Write the Docs. If like me, you’re based in the UK, its slightly more difficult but there are a number of options:

1. Use your training budget – Ask if you can use your training budget for the trip. It cost me my annual budget but it was well worth it and I was able to combine it with a trip to my company’s head office in San Francisco.

2. Become a speaker – I met a few writers whose company paid for them to be there because they were speakers. It’s great exposure for you, your documentation team and your company.

3. Recruitment  – If you’re company needs to grow its documentation team, you might be able to justify the cost by attending because there is a job fair and you have the opportunity to network and meet writers with a wide range of experience.

4. Exposure – Even if you don’t become a speaker, it’s a great way to raise your personal profile and that of your company. You never know when that visibility might come in handy in future.

5. Specific talks – Highlight a few specific talks from the schedule of the upcoming conference or a previous conference that may benefit you or your team. Write the Docs is a fantastic opportunity to learn from some of the best technical writers in the business!

If all else fails, see the sample email and other tips under the ‘Convince Your Manager‘ section of the Write the Docs website.

 

👽 The Emoji Invasion

A critic labelled the ‘text speak’ of the 1990s as “penmanship for the illiterates” but the latest threat to written English is the emoji, said to be the fastest growing language in the UK. While ‘text speak’ saw words shortened and abbreviated, emojis have replaced text altogether, harking back to the dark ages of cavemen and hieroglyphics, when pictures formed the basis of communication.

The rapid spread of emojis into modern communication has seen a translation company hiring the world’s first emoji translator, a restaurant launched in London with an emoji menu and the recent release of the Emoji Movie in our cinemas. So, where did they come from and is there a place for them in modern communication and technical writing?

🎬 Origins of the Emoji

The emoji first appeared on mobile phones in Japan during the late 1990s to support users’ obsession with images. Shigetaka Kurita, who was working for NTT DoCoMo (the largest mobile-phone operator in Japan), felt digital communication robbed people of the ability to communicate emotion. His answer was the emoji – which comes from the Japanese ‘e’ (絵) meaning “picture” and ‘moji’ (文字) “character”.

2000
One of the original set of 176 emojis designed by Shigetaka Kurita

The original emojis were black and white, confined to 12 x 12 pixels without much variation. These were based on marks used in weather forecasts and kanji characters, the logographic Chinese characters used in Japanese written language. The first colour emojis appeared in 1999and other mobile carriers started to design their own versions, introducing the smiling yellow faces that we see today.

aa-Cover-4fu6auljfsrl2jr5qirr1deh76-20161217051451.Medi
Shigetawa Kurita, the 👨‍👩‍👧 father of emojis, felt digital communication robbed people of emotion.

Speaking to the Guardian, Kurita admitted he was surprised at the popularity of emojis. “I didn’t assume that emoji would spread and become so popular internationally,” he said. “I’m surprised at how widespread they have become. Then again, they are universal, so they are useful communication tools that transcend language.”

“I’m surprised at how widespread they have become. Then again, they are universal, so they are useful communication tools that transcend language” – Shigetaka Kurita.

However, Kurita doesn’t believe emojis will threaten the written word. “I don’t accept that the use of emoji is a sign that people are losing the ability to communicate with words, or that they have a limited vocabulary,” he said. “Some people said the same about anime and manga, but those fears were never realised (…) Emoji have grown because they meet a need among mobile phone users. I accept that it’s difficult to use emoji to express complicated or nuanced feelings, but they are great for getting the general message across.”

💹 Emojis in Marketing

It is this ability to get the message across very simply that has resulted in companies using emojis more and more in marketing, particularly on platforms like Twitter and via email. It has become a way for brands to humanise themselves, have a sense of humour or put across a message that a younger audience can relate to.

One example of emoji marketing is a Tweet sent by Budweiser which was composed entirely of emojis to celebrate the 4th July this year:

Meanwhile, Twentieth Century Fox took emoji-based humour to whole new level with posters and billboards bearing two emojis and a letter (💀💩L) to announce the release of Deadpool in 2016:

Deadpool.png

✍️ Emojis in Technical Writing

A number of tech companies, especially those with a younger (in their 20s-40s) target audience like Slack and Emoji, have also embraced the use of emojis in their technical documentation and the software itself.

Slack3.png

Slack use them sporadically in the product, often as the punchline of a joke or message when you’ve read all unread threads (see screenshot above).

Emojis also appear in their help system, with Emoji flags for the chosen language and to highlight bullet points (see below):

Slack-emoji2

Startup bank Monzo also embraced emojis early on, designing an emoji-rich interface that would a younger client base than typical banks could relate to. Emojis are automatically assigned to transactions and you’ll find them incorporated in the Monzo API documentation and the app’s Help screen:

Monzo-mojis

iPhone6---Front-Black---by-JustD

Speaking to brand consultants Wolf Olins, CEO Tom Blomfield explained how they also use machine learning to pair your transaction’s spending category with relevant emoji. For example, it will display the doughnut emoji 🍩 when you shop at Dunkin Donuts. He said: “There’s no business case for the emoji donut, but people get ecstatically happy when seeing it and go on social media to share the moment.”

☠️ Risks of using Emojis

While emojis might work for some tech companies and give them a way to humanise their brand and relate to their target audience. I think there are several risks which come with their use as well.

The first risk is alienating users who don’t relate to emojis, or even dislike them. Although most of my office do use them as a way to react to each others’ Slack posts etc, there are a number of people who refuse and as there are a lot of nationalities with different cultural references, sometimes the emojis are used in different ways. For example, in Japan the poop emoji (💩) is used for luck while the English use is a lot more literal. Similarly, the folded hands emoji (🙏) means ‘thank you’ in Japan, while it is more commonly used to convey praying or saying ‘please’ in English usage.

Secondly, if emojis are just a fad like the Kardashians, Pokémon GO and Tamagotchi then you face the unpleasant task of replacing them all when they become unpopular, are considering annoying or are phased out. If you have saturated both your product and documentation with emojis then this task will take you and your team a lot of time and effort.

Thirdly and finally, studies have shown that emojis can get lost in translation as they are incredibly subjective so the meaning and intended emotive message can often be misinterpreted. This has continued to get more and more muddled as different vendors and browsers redesign and create their own versions of the unicode emoji characters. A study by GroupLens research lab found evidence of misinterpretation from emoji-based communication, often stemming from emojis appearing differently on different platforms.

Screen_Shot_2016-04-11_at_8.49.09_AM

The grimace emoji (😬) is said to cause the most confusion, with researchers finding that 70% of people believed it to be a negative reaction while 30% thought it conveyed a position emotion.

On the whole I don’t dislike emojis or think they’re a threat to the written word. They definitely have a role to play in social interaction, can humanise communication and even add humour to it. However, I still feel there are too many risks, too many different cultural interpretations which mean they simply won’t work in a multinational business. Technical writing is all about choosing the clearest form of communication, the shortest, most simple words that cannot be misunderstood. I’m just not convinced there’s a place for emojis in documentation yet, at least not while there is still room for things to get lost in translation.

Five Reasons I’m Falling Out with Confluence 

After a tumultuous and slightly short-lived affair with Sharepoint, I was introduced to Confluence and I was quickly won over by its simplistic UI and text editor. However, three years later I’m starting to feel disillusioned and frustrated with it. Here are some of the reasons why:

1. Bloat

Confluence has become bloated. I’m not sure if it’s a result of popularity or customers’ demands for new features but the feature set has been bloated while the basic functionality is neglected. It’s like a pet dog that has become fat and lazy from too many treats.

160402182953-tease-overweight-dog-update-irpt-full-169
Confluence now and Confluence before …

2. Bugs

Any frequent user of Confluence will be aware of the numerous bugs that seem to go unfixed for long periods of time. We encountered  a bug last week where images were breaking when copying a page (we later discovered this was caused by the image name having a colon).

Another common bug, which has caused me grief in the past, relates to being unable to export pages as PDFs for various reasons. This case, first reported in 2014, is still affecting customers two years later: https://jira.atlassian.com/browse/CONF-34275

2017-03-19 12_43_51-Clipboard
An example of customer frustration…

3. Plugins

To do anything useful or practical with the vanilla version of Confluence you need to install expensive plugins. Want to use versioning? You need buy a plugin. Want to translate your content? You need to buy a plugin.

2017-03-19 12_59_12-Films & TV
Even “Atlassian Verified” plugins don’t seem very reliable and are often costly.

Apart from the additional costs, my main issue with this is only a handful of plugins are built and maintained by Atlassian so you either have to take the risk of using a free plugin that will break in the future or you have rely on a third party developer to continue supporting it to ensure it works with newer versions of Confluence.

4. Basic Missing Features

The basic text editor in Confluence, the thing at the heart of the software, is still pretty poor and even things like basic formatting are a chore unless you manipulate the CSS.

2017-03-19 13_20_33
It amazes me Confluence still doesn’t offer other fonts or the option to change the font size.

Off the top of my head, the things that annoy me include: you can’t insert certain macros directly after another macro or a table because they will break or it will mess up your formatting, you can’t create a table without borders (unless you have Source Editor), you can’t choose different fonts or font sizes (unless you import them in the CSS), you can’t change the background colour, you can’t justify your text and you can’t remove historical attachments that have been uploaded to a page in the past. These are all things I’ve just accepted as Confluence-isms, things you just have to accept that Atlassian aren’t going to fix any time soon.

5. Cost

Despite all these things, Confluence is not cheap. If you’re a company with 100 or more employees, the Cloud version will set you back 3,000 dollars (£2,419) each year:

2017-03-19 13_24_50-New notification
Ouch: Confluence is not cheap!

On reflection, it’s pretty scandalous how much they are charging when so many bugs still exist, basic text editing functions are missing and most companies will need to install and pay for further plugins to get it to meet their requirements. Unfortunately, until someone comes up with a decent alternative I don’t see things changing.

Have you found a decent alternative that can be used for wiki content or software documentation/online help? If so, please let me know!

UX Design: The Good, the Bad and the Ugly

The Good

One of the nicest pieces of UX design I’ve come across recently is the Monzo banking app. When a friend from university said he was part of team setting up a bank it piqued my interest, partly because it sounded so ambitious and partly because I worked in the payment industry at the time.

monzo_horz_lightbg

Founded in 2015 as Mondo before a legal dispute forced them to change the name, they are part of the new crop of so-called “challenger banks”, set up to battle the old guard of banking institutions who are losing touch with their customers, the smartphone generation in particular.

Their USP is that Monzo is built with the latest modern technology (developed in Google’s coding language Go) so is “as smart as your phone”, easy to use and is able to offer instant notifications when payments are made.

monzo-screen

spending

It’s difficult to convey how nice the UX is in a still image but the app is incredibly clean and intuitive and makes it a fun way to map your spending. As you make purchases on your Monzo card they appear instantly in your app where you can see the name of the merchant, the amount spent, as well as map location, the category that your purchase fits into (entertainment, transport, groceries etc) and it is possible to attach a receipt and a note, completed with emojis. Overall, it’s just a very pleasing app to use.

The Bad

One my tasks at work is to send out version releases and patches using a piece of software called BizWizard which is made in Sweden. I’m going to be brutally honest, the old version of the product really sucked and I dreaded using it because I had so many issues with it.

bizwizard_retina_660

For starters, it wouldn’t run on Google Chrome and would crash unless running with Edge or Firefox.  I also found that most of my time on Bizwizard seemed to be spent watching the same grey progress bar as it slowly moved from screen to screen:

bizwizard

I thought it might be related to the amount of messages being stored but it is slow to navigate between most screens, even those without much data. It just made the entire experience of using it very dull and frustrating.

I’m not going to be totally negative about Bizwizard because the latest version is a dramatic improvement and for the most part, it’s really easy to use. I just encountered one more issue that I didn’t like in the new version of the content editor, which is that when I finished writing a message, my natural inclination was to click the prominent blue Revert button at the bottom of the screen, assuming that was the Save button (See screenshot below):

bad-ux
The Revert button which tricked me into thinking it was a Save button in BizWizard.

It’s probably a result of using Confluence, where the Save button is in the button right (see below), but as a result of clicking Revert my text was wiped with no way to undo or get it back. Very frustrating as a first time user of the new version.

confluence
The Save button in Atlassian Confluence.

I suppose I can’t be too hard on BizWizard for creating a button in a similar style and position to Confluence but it shouldn’t have so much prominence because it is a more natural place for a Save button. I’ve sent my feedback to them so it’s up to them whether they change it or not.

The Ugly

Linkedin is actually an app I use quite a lot and occasionally use to share my blog posts but unfortunately there are quite a few things I don’t like about it and the overall experience.

linkedin

Apart from the feeling that the “professional network” is striving to turn itself into Facebook and forever tries to force connections on you, there are other things that annoy me and just make it an unpleasant and sometimes annoying user experience.

Take the homepage for example, there is just so much going on. It’s just a bit of an information overload and makes me want to close it down. See screenshot below:

linkedin-2

There are so many things that demand your attention here in my opinion, with the orange warning bar about emails at the top, the yellow button begging to be pressed so I can reconnect with colleagues (not today thanks), blue links encouraging me to improve my profile and grow my network, an advert asking me to try Hired today, and a tab informing me I have one new update (and that’s having already read my notifications). It’s just far too much, like a needy kid screaming for attention, a lot of it just unnecessary and off-putting. It ruins the user experience.

In contrast, the smartphone app version is actually really nice to use and much cleaner than the web version. It’s a much more enjoyable user experience with a nicely designed UI and much less information to deal with. See screen below:

linkedin23

The only negative is the red notifications are often unclear so I don’t always know what I’m getting notifications for and there still seems to be an ongoing issue with messages/emails,  for example receiving and sending duplicates of the same message.

As a technical author I do find myself looking at software and applications through the eyes of a first time user/ tester so I’m maybe I’m being harsh with my criticism but development teams should always consider the user, their experience and how they would expect or like your product to work. If your product doesn’t work how they would expect it to, if they find it difficult to navigate or if they find the overall experience annoying or frustrating then they are unlikely to want to use it again and that’s bad news for business.

Please note: User experience is always going to be subjective so some people may agree or disagree with me about these examples. It goes without saying that all of the opinions above are my own and not those of my employer!

Funny Typos & Spelling Mistakes

Typos and spelling mistakes can be embarrassing but even the most experienced content producers and technical writers make them. Here are a few examples of unfortunate typos which serve as a funny reminder to always double-check your copy before it is released!

1. The existential crisis. Are you sure you want to exist?
nFqVG4N
Credit to Reddit user /u/psychob

2. Shit happens. A really unfortunate misspelling of shoot by Pentax.

3szEjQe

3. Beyond parody. British Government announces new language test for migrants with an embarrassing misspelling.

u-k-english-requirement-announcement

One of the first people to spot the mistake was Nick Wallis from BBC’s The One Show:

4. Child’s Play: It’s important to know the difference between “they’re” and “their”.

creative_kids_software

5. Regsiter? Nah, I think I’ll register with a company which doesn’t make spelling mistakes.

hubspot-typo

6. Reeding between the lines: I don’t think this Yellow Pages advert was proofread.

Proofreading

As the examples above show, we’re all human and mistakes do happen but they may cost your website, business or documentation their credibility and sometimes money. Always double-check your copy before publishing it.

The Role of Text in UX

As software and apps become more user-friendly and commonly-used icons become universally understood, there is a growing tendency to scrap text.

Microsoft experimented with the minimalist icons-over-text approach in their release of Outlook 1997. As you can see from the toolbar, they left out the text descriptions and as a result non-experienced Outlook users apparently stopped using the toolbar altogether:

2016-07-06 16_01_02-ToolbarCompare-11-1-2005.png (590×113)
Microsoft Outlook 1997
Several designs later, with Outlook 2000, they had a rethink and text was added back in:

2016-07-06 16_06_09-outlook01.gif (768×537)
Microsoft Outlook 2000
While more recent designs are less icon-assisted and text has even clearer prominence:

2016-07-06 16_09_20-Inbox - james.scott@hoistgroup.com - Outlook.jpg
Microsoft Outlook 2013

Digital designer Thomas Byttebier makes some excellent points about the importance of using text in his blog here, with the concluding statement being “when in doubt, the best icon is a text label.” He lists a number of extremely popular apps and sites where icons are pretty ambiguous. Take Instagram and Spotify for example. Are people aware of what this icon actually does?

2016-07-06 17_13_37-Start

2016-07-06 17_12_09-Spotify

In both cases this in-tray icon is for accessing your inbox and sending direct messages but I think the messaging feature is clearly overlooked in both applications. When I asked friends who have been using the applications for several years whether they were aware of the messaging feature they just looked at me blankly. One said “Oh, that bikini thing”, the other thought it was a basket. So there’s clearly a lack of clarity over the  purpose of the icon but whether that’s due to the ambiguous design or a lack of need, I’m not sure. It’s probably a bit of both.

Twitter have also had some issues with ambiguous and non-universal icons, often presuming that users will just intuitively understand what the icons do and sometimes getting it wrong. As a result Twitter’s user growth has actually slowed as new users that are attracted to the site often have a hard time catching on to how it works.

pict--iphone-screen-template---messages--messages---templatepict--iphone-screen-template---messages--messages---template2

The arrow icon for ‘Reply’, the envelope icon for ‘Message’ and the ellipsis (three dots) ‘More Options’ icon are recognisable but the heart icon for ‘Like’ will only be familiar with people who have used Instagram and other social media. A new user is unlikely to know what the ‘Retweet’ icon does unless they are familiar with Twitter’s basic concepts. It is interesting to note that Twitter have added text labels to the bottom five icons (highlighted in green in the image above) because other than perhaps ‘Messages’ their function is not obvious to the user.

While documentation is sometimes seen as an afterthought in the development process, in my opinion the text and written content is an inherent part of user experience for all software, no matter how intuitive the UI designer thinks his icons are or user-friendly the product is. If you want to avoid ambiguity, text will always be the best way to get the message across to the user.

10 Tips for making Content more Engaging

I’ve always liked to learn new bits of software by trial and error, trying things out for myself first and learning from my mistakes but there’s only so far you can get before you get stuck. This is why documentation and help are so invaluable because a piece of software is worthless unless you know how it works.

1c00898.jpg

In today’s fast-paced world, people don’t have time to read chunky 900 to 1000 page manuals, they want information to be quick and accessible. As a result, technology companies and their technical writers are having to adapt their techniques and content strategies to make documentation more exciting and engaging for readers.

Here are some of the best ways to keep people interested in your content:

1. Pictures

As you have probably seen from my blogs, I am a real advocate for using good images to break up text and make documentation more approachable and more visually interesting.

2016-05-20 11_32_36-Mozilla Support.jpg

This is just the Firefox help homepage but as I mention in my blog last week, I thought the design and use of imagery was really visually appealing.

2. Videos

Taking this approach one step further, videos are another brilliant and effective way to engage help users as long as they are well put together, short and succinct.

The example above is one of Skype’s excellent video tutorials which are really well produced.

Videos can be made with software such as Camtasia or free tools such as Open Broadcaster Software.

3. Gifs

Like videos, it is possible to add gifs to make your content more dynamic and visually interesting. They are a quick simple way to show an example of how something is done:

Animation

This gif was produced using free open-source software called ScreenToGif.

4. Infographics

I think graphics are a great way to get a lot of information across to your readers in one image if they are designed well.

all-about-spotify-and-ecosport_527a5b85c6af0_w1500

The Spotify infographic above has 10 separate facts spread across one image.

5. Examples

Using examples is the best way to show your readers what you are trying to explain.

2016-06-02 14_05_27-Embedding a Tweet on your website or blog _ Twitter Help Center

On the page above, taken from the Twitter, the help describes how to embed a Tweet and then gives examples.

6. Be Human

Use an informal or conversational writing style. Write as if you were describing how the software works to a friend. Readers won’t engage with a robotic tone of voice.

2016-06-02 14_07_29-People You May Know _ LinkedIn Help

Linkedin’s Help addresses users by their first name to make the experience more personal.

7. Keep it Short

Don’t overwrite. If you can explain it in one sentence then write one sentence. It’s better to use 25 words rather than 250. The shorter the better.

2016-06-02 14_10_12-Login Basics _ Facebook Help Centre

Facebook’s Help Centre covers the login basics in just 73 words (and three links).

8. Keep it Simple

Don’t use lengthy words the average person won’t understand or that will get lost in translation. Go with “move in a circle” rather than “circumbilivagination” or “use” instead of “utilise”.

2016-06-02 14_14_05-Start

Sorry Royal Mail but I really dislike the use of “utilise”, it’s just a waste of four letters!

9. Easy Navigation

If your help system is easy to work your way around then people will want to use it.

2016-06-02 14_20_59-Start

Skype’s Help is really easy to navigate from my experience. You can check it out here.

10. Make it fun!

Use humour and unusual text to catch people’s attention. This is discussed by Mozilla’s Michael Verdi in his presentation How To Write Awesome Documentation.

Atlassian Confluence’s help system, shown below, encourages new users to join a fictional space program and complete a mission:

2016-06-01 14_40_40-Get started - Atlassian Documentation

2016-06-01 14_40_57-Tutorial_ Navigate Confluence - Atlassian Documentation

Sure, it’s a bit wacky and off-the-wall but its fun, it catches attention and keeps readers interested and engaged.

Help Review – Mozilla Firefox

I stumbled across Mozilla Firefox’s help system last week and was interested to find most of the articles were largely written by volunteers. I hadn’t come across this kind of model for documentation before so it raised some interesting questions. For starters, can a group of volunteer technical writers collaborate to produce an effective help system?

2016-05-20 11_32_36-Mozilla Support

Mozilla released Firefox as an open-source web browser back in 2002 and as such the source code is open to anyone. As a non-profit organisation, Mozilla also relied heavily on the code, along with the support and documentation being largely maintained by volunteers. Although the company now has a large workforce of paid employees, an army of volunteers also still contribute to roughly 40% of its work, which includes not only the documentation but also coding tweaks (around 24% of all source code changes) and even the Firefox logo design. The help system was created through the SUMO technical writing program, which invited participants (a mixture of college students and technical writing professionals) to take part in each release cycle in order to produce the documentation. Although the program is not currently active, the participants and other volunteers still seem to be actively involved in maintaining the existing help articles.

Firefox-3

First Impressions

Visually, I think the design and layout of the Mozilla Support homepage is really appealing, with all of the individual products and their logos mapped out in different sections. It just looks cool. The simple grey background, contrasting with the colourful designs of the Mozilla product icons and clearly marked out sections make it very easy to navigate. It was interesting to discover that some of the legacy of Mozilla’s design is down to an interface designer called Steven Garrity wrote an article listing everything that was wrong with Mozilla’s visual identity back in 2003 and was subsequently invited to their head office and asked to head up their new visual identity team which led a re-brand in 2004 when the now well-known Firefox logo, designed by Jon Hicks, was introduced.

2016-05-24 12_55_59-Start

The help is broken down into nine help topics, with multiple articles under each topic. The documentation itself is clearly laid out, although the screenshots are sometimes different sizes and formats (some fade into background, some do not etc.) and it is easy to spot where different technical writers have worked on the same article and used different styles to highlight sections of a screenshot. In the example below, you can see three different contributors’ work, with one opting for a crimson red rectangle to highlight ‘Desktop’, another using a orange-red circle and the third person using a brighter scarlet red oval:

Inconsistent

Each page does actually list the authors of each article so it is possible to see how many people have contributed to each article. This particular article had eight contributors but other have even more, and unfortunately it shows:

2016-05-31 12_31_59-How do I tell if my connection to a website is secure_ _ Firefox Help

In this article, which had 22 contributors, there were little issues like the screenshots being slightly different sizes. While it’s not the end of the world, the different styles of writing and formatting are pretty noticeable, even for someone without mild OCD, and it can look a bit messy and unprofessional. I guess it’s the kind of thing that’s forgivable when you’re using a free open-source browser but it could be easily remedied if Mozilla implemented a style guide for all contributing technical authors to ensure there is more uniformity with terminology, screenshots and how things are highlighted. Alternatively an editor could go through and make edits to clean things up where necessary.

Features

One thing I was really pleased to see in the help was the occasional gif clip and a good number of tutorial videos which ensure the content is dynamic and semi-interactive for its readers. The videos, which have been produced by Mozilla senior UX designer Michael Verdi, are short and well edited so they are very watchable. He has a personal, informal style and friendly tone which is more engaging than a robotic Siri/Cortana-style  narration.

At the top of each article, there is also a drop-down menu on the left-hand side which has some pretty useful features such as a link to any discussion items on the article’s topic, multiple language translations of the article, showing what other articles are linked to the article you are reading and seeing the history of who contributed and edited the article.

2016-05-27 11_44_48-Photos

In terms of help and support, it has three main branches: Twitter, a support forum and help articles. Again, this is a great way for Mozilla to keep all of their bases covered. The other great thing people volunteer to assist with all three of those branches as well, with volunteer contributors on Twitter, volunteers answering questions on the support form and volunteers writing the help articles themselves. These volunteers are prompted to help by various Volunteer for Mozilla Support buttons, as shown in the screenshot  below:

2016-05-26 14_34_31-Start

There is constant encouragement to get involved in things like the “Army of Awesome” (their Twitter helpers) and statistics about how help matters. For example, “1 Tweet can save 1 day” and “1 article can be viewed by 400 million users”. It just has a really positive, pro-active community feel about it.

Another common theme is the carton Firefox character, who is like a superhero-type figure, which appeals to everyone’s inner geek. It’s another simple but effective way to make  the support pages fun and engaging.

This slideshow requires JavaScript.

Conclusion

I am really impressed with the content and support that is being produced by Mozilla, especially given the high percentage of work being done voluntarily. On top of the written content, they are also managing to offer video tutorial content and a Twitter help account which are further supported by a support forum. It would be useful to have a style guide or some kind of lead technical author/editor to iron out any issues with uniformity but overall I think Firefox’s support pages prove that open source projects can be reasonably well-documented through crowd-sourcing volunteer technical writers. I’m not sure this model of documentation would work for everyone but I think Mozilla have proved that volunteers can collaborate to produce an extensive help system, this clearly isn’t just a big work experience project.