All posts by jwscott22

About jwscott22

Technical author

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.

 

Bernard-Paul Heroux: Fact or Fiction?

If you Google for quotes about tea, one of the top hits is from the philosopher Bernard-Paul Heroux who is attributed with this quote:

There is no trouble so great or grave that cannot be much diminished by a nice cup of tea.

The philosopher’s words of wisdom about tea are quoted in articles by the Telegraph, Reuters, the Guardian and numerous blogs and websites online. An image search also shows that the Tregothnan estate in Cornwall and American retailer Trader Joe’s use the quote on their packets of tea.

This slideshow requires JavaScript.

The former journalist in me wanted to find out more about the mystery man behind the famous phrase. Searches of the name Bernard-Paul Heroux return no wikipedia listings and his name isn’t listed alongside other famous Basques or famous Basques philosophers. In fact, the only hit I got at all, aside from the quote, was that the Heroux name was a surname from the Languedoc-Rousillion region of France, a good six hour drive from Basques country. However, the Heroux surname is not listed in any online database of Basques surnames and trawling several sites of Basques births, deaths and marriages returned nothing. It’s as if Mr Heroux appeared at some point in the 1900s, made his famous quote about tea and then vanished into thin air.

Apart from the lack of evidence he ever existed, my other major doubt around the authenticity of this phrase is the fact that Basques country, as with other parts of northern Spain, has had has much more of a coffee-drinking culture for centuries. It’s just a fact, the Basques and the Spanish are traditionally coffee drinkers – not tea drinkers.

So is Bernard-Paul Heroux’s quote fact or fiction? Was he a real man or it just a figment of the imagination, dreamed up as part of an elaborate piece of marketing? I don’t want to make a storm in a teacup but until someone can prove to me otherwise, I think it’s probably the latter.

 

👽 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.

Debugging the word ‘Bug’

Etymology and the origin of English language have always fascinated me, partly because so many of the words we use every day represent remnants of history; artefacts left behind by the Roman Empire, the Vikings and the Norman conquest. Although words relating to computing and technology are much younger, some are just as quirky and steeped in history as those from the past.

Like a Moth to a Flame

The origin of the word ‘bug’ in the computing world is often mistakenly credited to computer scientist Grace Hopper. The story goes that while working on the Harvard Mark II computer in 1947 she discovered a dead moth stuck in a relay. It was removed and taped into a logbook where she wrote “First actual case of a bug being found” (see picture below), which suggests that the term was already in use at that time.

H96566k

While this might have been the first literal case of ‘debugging’, there is evidence that ‘bug’ had been used in engineering for many years before that.

Scarecrows, Bugs and Bogeys

The most accepted origin of ‘bug’ is the Middle English word ‘bugge’ or ‘bogge’ (n.), which meant a scarecrow or a scary thing. One of the first iterations of the word came in John Wycliffe’s English translation of the bible (circa 1320-1382): “As a bugge either a man of raggis in a place where gourdis wexen kepith no thing, so ben her goddis of tree.” (As a scarecrow or a man of rags in a place where gourds grow guards nothing, so are their gods of wood.)

Bugs-2.png
‘Bugge’ (n) originally meant scarecrow then became an early name for bedbug.

As language evolved, another off-shoot of ‘bugge’, the scarecrow, was ‘bogey’, an evil or mischievous spirit. This gave rise to a family of other ghost and hobgoblin names including ‘bogeyman’, ‘boggart’, ‘bogle’ and ‘bugaboo’. While the archaic form of ‘bugbear’ is also another hobgoblin figure. In general these all have the same negative connotation of things to avoid and that cause fear or irritation. The direct descendant of these words is ‘bogey’ which still survives today in modern English, in aviation where a ‘bogey’ is an enemy aircraft, in golf where a ‘bogey’ is one over par (a bad score) and a ‘bogey’ (UK) or ‘booger’ (US) is a piece of nasal mucus.

giphy (1).gif

By the middle of the seventeenth century, the word ‘bug’ no longer meant scarecrow and had come to mean ‘insect’, which makes sense as many people consider them to be alien and scary. The earliest references to ‘bugs’ meaning insects often related to ‘bedbugs’, supposedly because when someone woke up covered in bedbug bites, it was as if they had been visited by something scary during the night.

Thomas Edison’s Bugs

By the 1870s, the meaning of bug had changed once more and perhaps made its first appearance in technology when American inventor Thomas Edison referred to what he called a ‘bug’ while developing a quadruplex telegraph system in 1873. He also mentioned ‘bugs’ in a letter to an associate:

“It has been just so in all of my inventions. The first step is an intuition, and comes with a burst, then difficulties arise — this thing gives out and [it is] then that “bugs” — as such little faults and difficulties are called — show themselves and months of intense watching, study and labor are requisite before commercial success or failure is certainly reached.”

They were mentioned once again in an article in the Pall Mall Gazette in 1889:

“Mr. Edison, I was informed, had been up the two previous nights discovering ‘a bug’ in his phonograph – an expression for solving a difficulty, and implying that some imaginary insect has secreted itself inside and is causing all the trouble.”

Another early example of ‘bugs’ being used to refer to technology was with the release of the first mechanical pinball machine, Baffle Ball, which was created by David Gottlieb in 1931. It was advertised with the strap-line “No bugs in this game!” (see poster below):

No-Bugs1
So it seems fair to assume that the word ‘bug’ came from ‘bugge’, the Middle English for scarecrow, which led to ‘bogey’ and all the similar words meaning an obstacle, a source of dread or something to be feared. In modern times the word ‘bug’ has become a verb meaning to vex or irritate, while the noun form has become a synonym for disease-causing germs, crazily enthusiastic or obsessive people (e.g. a firebug is a pyromaniac), concealed recording devices used by spies and perhaps, thanks to Edison, an error in technology.

 

 

 

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!

The Basics of JavaScript

For the past month or so I have become somewhat immersed in JavaScript. As I already knew the basics of HTML and CSS through using WordPress and other CMS tools, I took the plunge and started to learn JavaScript, the other core web development language, using Codecademy and w3schools.com.

What is JavaScript?

JavaScript is an object-orientated programming language that is derived from C + +. It is a scripting language normally used to create interactive effects within web browsers. JavaScript’s dynamic capabilities include run-time object construction, variable parameter lists, function variables and event loops, some of which I will discuss below.

JavaScript Syntax & Operators

Variables are containers for storing data values. These are declared by the var keyword:

Var

Functions are used to perform defined tasks. These are declared by the function keyword.

2016-08-25 14_30_35-Introduction to Functions in JS _ Codecademy

A function will only be executed when it is called/invoked. e.g. In this case the function is called “greeting” so the input below will return “Great to see you Dave”.

greeting ("Dave")

Return is a statement used to stop the execution of a function. It will also return the value of a function.

var x = myFunction(2, 4);        

function myFunction(a, b) {
    return a * b;                
}

In the example above, x will be returned as ‘8’.

Console.log commands are used to display data . Console.log() will take whatever is inside the parentheses and log it to the console.

2016-08-25 16_27_53-Getting Started with Programming _ Codecademy

In this case, the information logged to the console will appear as:

2016-08-25 16_29_59-Getting Started with Programming _ Codecademy

If/else statements are used to make decisions in the code. An if/else statement will execute one block of code if a specified condition is true, if the condition is false, another block of code can be executed.

if-else

Loops are used to execute a block of code a number of times. Loops are useful if you want to run the same code repeatedly with different values. It’s all about getting the computer to do the legwork for you, as opposed to typing out numerous lines of code.

Here is an example of a for loop. This will run 5 times, with values of ‘step’ 0 to 4.

var step;
for (step = 0; step < 5; step++) {
  console.log('Walking east one step');
}

Different loop types include:

for – this will loop through a block of code a number of times.
while – this will loop through a block of code while a specified condition is true.
for/in – this will loop through the properties of an object.
do/while – this will also loop through a block of code while a specified condition is true.

Arrays are special types of variable that can used to hold multiple values at one time.

For example, if you wanted to list a number of values from one array you could use a block of code like this:

var beers = ["Heineken", "Amstel", "Carling", "Fosters"];
for (var i = 0; i < beers.length; i++) {
console.log (beers [i]) ;
}

This would return:

Heineken
Amstel
Carling
Fosters

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.