GitLab UX Team, 1 Dec 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: UX Showcase - Plain Language in UX Writing

Description

Slide deck: https://docs.google.com/presentation/d/e/2PACX-1vSz3rQf2KKQ9Sec2iXeatyy3MY-pHKvEF236EK616gjMfWI5ztSlSSdIA7ipLmmiLHp0Po5YtvrYyDU/pub

Manage & Plan
UX Showcase - Dec. 1st, 2021

A

Hi so I'm marcin sędłak-jakubowski- and I am the technical writer for plan.

A

Today, I want to talk to you about using plain language in ux writing.

A

So writing for interfaces writing for user docs.

A

So, let's start on why I started thinking about it is that earlier this year I took part in.

A

In a conference online conference for ux writing, it covered a whole range of topics.

A

One thing that was specific to that conference is that it all happened in polish, so.

A

All the talks were focused were tailored for the polish speakers, usually working in english.

A

So this is why I say on this slide that this presentation is inspired by this conference.

A

Because I took some of these ideas and adapted them.

A

For us., and to give you an example of things that polish speakers deal with.

A

When they have to work in, for example, in both english and polish, is that.

A

When writing for interfaces polish can be very. This is my opinion that polish is very sensitive.

A

To tone it's very easy to be too formal or too friendly, and I find it much easier to strike this.

A

This balance in english, so, first of all what is plain language- and I brought two quotes here.

A

One is from plainlanguage.gov a us website that I'm going to be referencing throughout.

A

The presentation, because it has tons of useful resources and the other one, is also from the us.

A

Plain writing act of 2010., and so plain language is language that is easy to understand.

A

The first time you consume it, it's language that communicates quickly and clearly um one.

A

Of its features is that it's easily scanned, and we know that it's preferred by everybody.

A

One thing that you have to remember is that being direct and plain spoken.

A

Is not talking down it's clear communication.

A

So how do we know it's preferred by everyone.

A

So nielsen norman group has done a study where they had domain experts from different fields.

A

Evaluate pieces of writing, or, as you can see here, like full websites for helpful articles and.

A

Talking on which ones would they prefer, which ones are clear to consume?.

A

And here we have a verbatim from a nurse practitioner with a doctorate.

A

So moving on here are some examples of plain writing in use before we go to.

A

The five tips that will help you be successful at ux writing so here is.

A

An example also from plainlanguage.gov this one describes medicaid eligibility.

A

And they also say that the example that they created the example that it's not.

A

Like an original text, that's a use case, and would you look at this beautiful list? I mean.

A

It's just, I have no words to describe how I like it, but words are not always necessary.

A

And in this example, this is, this is copy that describes a vehicle that describes how you use a car.

A

And if you want to put it inside a car, that's uh that might be much easier to consume.

A

With pictograms- and you can find more examples on the plain language.gov website.

A

Now, on to the tips, so number one is know your audience, and this is key for any ux activity.

A

Be it designing the ui writing the talks even for this presentation, right?.

A

And so what about us? What about gitlab? Well, we support all users from beginners to experts.

A

And we want our interfaces and documentations to the documentation to reflect that.

A

To users of different proficiency levels, and also we have a range of personas.

A

So I bet you all are very familiar with them, so once you get the feeling.

A

And understanding of who you're talking to you will be able to adapt the language.

A

That you're, using to your recipient so, for example, is it always bad to use technical acronyms? Well, if.

A

If you're deep in gitlab settings, for example, you might expect some knowledge.

A

On the side of the user, and so just to give you an example how we work worked in plan.

A

So a few releases ago we introduced iterations, and so we sometimes get feedback from from customers.

A

Why aren't they called sprints? Because this specific customer is using? You know a planning.

A

Methodology that uses sprints- this is because- and you have holly here and you know, find her later.

A

And you can ask her for more background. This is because sprints are exclusive to scrum or agile.

A

But iteration is a word that also includes sprints in other methodologies,.

A

So it might be unfamiliar to some users, but because we made this choice, it will cover.

A

More cases and won't dictate methodology, which is also something that we want to do.

A

But sometimes a technical word might be better than a common word, because well we.

A

Are in technical writing even like, even if you're writing for an interface, so, for example, you know.

A

Remember to use a thesaurus if you're, having trouble with synonyms so receive might be.

A

A better word in technical context because it describes exactly what's happening, whereas for.

A

Example get has a million meanings and it can be vague for users right while in colloquial conversation.

A

In common language, it would be easier to get, it would be, make more sense to use, get.

A

Because it's an easier word, so you might want to avoid get unless maybe you're using it in.

A

Api documentation right when you're referring to get requests. However, we do use it, but also.

A

The headings in our docs, they say list right, because this is what the user is doing so.

A

This way, this is more human oriented than machine oriented.

A

So tip number two is organize content. Logically, I don't have much to say on this. Besides, maybe that.

A

You need to put tooltips descriptions, errors where it makes sense and where.

A

The user is looking right and we have plenty of examples available within the gitlab ui.

A

Where the errors appear, when you're validating a password, you know show the.

A

The validation error close to the fields and not in some corner number three is be conversational.

A

And I summarize it I paraphrase it to myself as speak, like a human, you know.

A

So here's an example of an error. It is good often to list the technical.

A

Type of the error, if you know the user knows what to do with it later,.

A

But very often- and I don't know in mobile context, for example,.

A

It's much nicer to speak directly and to show empathy, especially when you're delivering bad news.

A

Don't blame the user and so here's a bunch of other tips that you can read at your own pace.

A

um This is this, is you know, good stuff to know in general, for ui writing and there's the link to.

A

A talk at the write, the docs conference on error message: writing.

A

And this is something that I remember, because it's an alliterative title.

A

Because you want your error messages to be humble human and helpful and number four is keep it brief.

A

So in ui text you know we are limited in space, so make every word earn its place. So here's.

A

Another example both of these you know both the before and after they express the same thing.

A

But the shorter one is what we would prefer and here are things that, if you see just.

A

Cut them out try and eliminate redundancies, so two words next to each other. They mean the same things.

A

Idioms because while they are fun, your readers might not be native users of english.

A

Pointless modifiers and meaningless generalities, so things as things that we have.

A

Heard many many times and you know, might even have negative reactions to seeing them again.

A

And finally, number five is test and revise. So when you're working with.

A

When writing ui copy, what you can use is readability scores.

A

You can put it through a website or test it for you in the docs. We use the vale extension to.

A

Lint our text, you can run through a checklist that, if you go to that link.

A

Well, there aren't check boxes, unfortunately, but the bullet points that are there are basically.

A

This presentation, in a nutshell, and also check in with users.

A

I have maybe twice while being here, I have helped with user research and it was eye-opening to me.

A

Seeing where the users struggle when using gitlab, and so that's the five tips that will make you.

A

Be successful when writing for uis and user documentation thanks.

A

Thank you so much marcin uh that was uh eye-opening to use your term.

A

uh Is that an idiom, um maybe uh any questions we andy posted a.

A

Helpful tool that he uses, but any questions that we'd like to discuss.

A

A

I'm going to say no and move on. Let's move on to alexis in.