For years we’ve treated documentation like a filing cabinet. Put the thing in the right folder and give it a label. But much as it pains me, people rarely wander through my carefully crafted hierarchy, admiring the taxonomy. They search, skim, follow links. And the second finding information feels like work, they’ve checked out and just asked someone.

I have to say, this was exactly my experience on a recent guidance project. Users would often find the document they wanted and make a direct copy to keep locally. Of course, when guidance was updated, that local copy was soon out of date.

For these users, knowing where to quickly find guidance was important. To heck with the shared folder structure! And for those times where they couldn't find the right guidance document at all, they would simply ask a colleague for the answer.

Needless to say, I learnt a lot from this experience. It's important to organise documents in a clear, sensible way that people can easily navigate. But don't think for a second that users will or want to carefully wander through your folder structure to find what they want.

If you don't already know a little code, I really recommend learning the basics of HMTL. It will help you understand how a page is structured in code and improve how you work with a developer. You can work with them to make sure your content is clear and accessible, including your headings.

Use our design decision template to organize your ideas and explain your design solution. Once you’ve brainstormed creative options, use the template to exchange feedback with your design team.

That last bit is worth thinking about, actually.

It doesn't have to be Confluence, but a tool that other people can easily see and contribute to is really important. The alternative? A document that festers deep in some long-neglected folder structure, never to be used by anyone but you.

We've all been there. Come one. Gets your docs out. Make them easy to find.

Design documentation is an important part of the design process. It records the thinking behind the designs. It preserves knowledge for future team members. It gives you evidence when stakeholders challenge design decisions. A screen-by-screen explanation ensures that you don’t miss anything. A decision log gives a high-level overview of the who and why of design decisions.

I'm in the process of documenting some of my design work at the moment. For example, I recently updated some content based on feedback from the clinical assurance team. So I made a note of that in our shared decision log.

Having that decision documented will help anyone new to the project understand that there is a very good reason why things are the way they are. They can be reassured that the design work was based on sound clinical guidance.

Read Baird's post if you want to get started with this kind of thing yourself. There is even a useful four-column example you can swipe for your decision log. Lovely stuff.

When we start working on an end-to-end service, we define the users, then map out the journey. This process shows us what tasks users need to complete and highlights where the content doesn’t help them to do this.

What follows is pretty much a step-by-step to get you started. Of course, you'll need to take your organisation's specific circumstances and constraints into account. But hopefully it should be easy to get the right people together and start mapping those content journeys. Also, you can do all this at the start of a content project, not just when things already exist and are ready for an update.

I suggest you first read these recommendations by Ema Thornhill, which provide a good introduction to the guidance.

Since I last emailed you, I have taken part in a very long bicycle ride and had my gall bladder removed. I can't recommend the latter experience, to be honest. Easily outside my top 40 experiences of the year so far.

Thank you for all the nice messages about the Clear Language Club blog. I've been posting regularly. Remember, you can subscribe to the RSS feed if you want to get the goodies without regular check ins.

Enjoy the following content feast.

Iain

Good content

How screen readers use headings to make table content accessible

I've been working in table land the last couple of months and expect more of the same over the summer. Tables are hard, especially when you are designing with a lot of data. This is a good video intro that explains how screen readers 'read' table headings.

Use of tense when referring to death

Excellent post on writing about death by Lizzie Cass-Maran. I added some of my own reflections from my time working at the Infected Blood Compensation Authority. Basically, it can be very difficult and sometimes it feels like there are no options that are both kind and clear. But this is what you are aiming for. And I just love those two words as fundamentals of good content design.

Intuit's guidance on anti-racist language

First, Intuit has an excellent, detailed style guide that is worth a browse. Also, this page on anti-racist language includes several statements of intent, followed by a useful list of terms with racist roots to avoid.

7 things you may not know about web accessibility

Good web accessibility intel from Andrew Tipp at Suffolk County Council. It includes the seemingly obvious but often overlooked reality that accessible content is better for everyone.

How to write error messages

Great tips on writing error messages in the Readability Guidelines. I've just spotted the Guidelines site is due to close down next month, so go grab your excellent content advice while you can.

3 tools I use

Here are 3 handy tools that I use every day when I'm going about my content business. I use a Mac, but I've included a Windows equivalent for the first one.

Cleanshot

Cleanshot is the best tool for taking and sharing screenshots, something I do sometimes multiple times a day. It has a great editor, which allows you to annotate your image or add a neat background before you share it.

Cleanshot is also a very good screen recording tool, though I rarely use it for that (see Descript below). If you sign up the cloud service, you can even collect a library of saved screenshots if that's what you're into.

Lightshot looks similar for Windows users.

TextExpander

I've used TextExpander for as long as I can remember. It allows you to create keyboard shortcuts for text that you use regularly. For example, your email or web address. Maybe the organisation you work for. Or even a stock paragraph that you are sick of copying and pasting over and over again.

TextExpander has added lots of features over the years. It's pretty powerful, especially if you enjoy tinkering away to try and save as much time as possible. And the good news, it's available across platforms, including mobile.

Descript

Descript is a video editor, audio editor and screen recorder all in one. But it has magic sauce. It transcribes an audio or video file into a text document. Then when you edit that text document, the audio and video are edited too. I've used it to make 100+ documentary episodes of a cycling podcast. And it's my go-to app whenever I want to do a quick content demo to share with the team.

Naming services is an important part of digital transformation. Service names need to be clear, concise and related to the task people are completing. But this can become harder when the situation becomes more complex.

The thrust of the post is about using dedicated workshops to get all the key people together:

An engaging naming workshop is a way of making sure that everyone has the same level of knowledge of what’s involved in this task, and the importance of it. Getting important stakeholders involved and as close as possible to this work will set you up for success.

I have one extra tip on naming your service. I learnt this the hard way last year. Before you start telling people your new service name, remember to carry out a quick check to make sure that any inevitable acronyms are not, well... a bit rude. Cripes.

Plain language relies on testing with users. If the intended users can use the content to do what they need to do, it’s plain. If they can’t, it’s not plain. So you can only really know whether you have succeeded in writing in plain language when you have tested with the actual users.

And of course, this detail is fundamental to content design as a discipline. It's about following the principles of clear writing, but making decisions based on research and data. You need to understand what users need before you start writing. Then you need to test your content when you're done to make sure it meets those needs. It's only plain or clear if it does.

Sure, these days it's more bloated than it needs to be, but it does still do the essential things you need to get your bits and bobs in order. This content template is very similar to the one I tend to use and is pretty good for getting started.

It looks like I'll be spending the best part of this year designing some pretty tricky tables. There will be lots of columns and lots of rows. More data that I can shake a stick at. And making all of it accessible is really important too.

Anyway, I'm expecting lots of learning. Lots of user research. And plenty of digging into resources that are already out there and available, like this quick video explainer from GOV.UK on how screen readers use headings.

One of the lovely colleagues on my previous project shared this blog post by Cap Watkins with me last year and I have thought about it a lot since. Essentially, if you are having a difficult design or content conversation, how much does the issue mean to you on a scale of 1–10?

There have been a few times recently when I could tell someone felt far more strongly about a decision than I did. So, I acquiesced, with the hope that the next time I'm a ten-out-of-ten on a topic with that person involved, they'll recognize that and hear me out. If you can let go of the things that don't matter so much to you directly, you can build currency with others and earn their trust when you do wind up pushing back.

I have found this an incredibly useful mental trick. When you are in the fog of deadlines and challenging work, it is easy to feel like every decision matters and all arguments are worth fighting for. But that's not how true collaboration works.

To work effectively as a team when things get tough and tense, there has to be a bit of give and take. You can't go full steam ahead into every single conversation. It's unlikely that your way will be the right way every time.

So yeah – these are good questions to ask. Is this decision – this argument – really that important to me? Do I feel so strongly about it? Or can I let this one go and save my persistence for a problem that's more of an 8, 9 or 10 out of 10?