This is a translation. If it differs from the Portuguese version, the Portuguese version prevails.
Why this matters
Many people use Mastodon differently from you. Blind and low-vision people listen to posts through a screen reader, a program that reads out loud everything on the screen. Other people have epilepsy, migraines or motion sensitivity. And many people read in another language, through automatic translation.
A few small habits when posting make your post reach all of them. Nothing here is hard, and almost all of it becomes second nature within days.
In one sentence: describe your images, write #HashtagsLikeThis, use few emojis and add a
content warning (CW) when the topic calls for it.
On bolha.us, describing images is a recommendation in the rules.
1. Images, GIFs and videos
Describe every piece of media (alt text)
Alt text, or ALT, is the description of an image that screen readers read out loud. Without it, people who can't see only hear "image" and have no idea what it is about.
- When you attach an image, GIF or video, click Edit (or the "Add description" prompt) and write what it shows.
- Say what matters to understand the post: what is shown, what is happening and any text written in the image.
- See how to write a good description in section 4.
No time or no idea how to describe it? Use descreve.bolha.us: mention @descreve@bolha.us in your post and the bot suggests a description (in Portuguese). Review and adjust it before using it, because nobody knows the context of the image better than you.
Watch out for flashing lights
GIFs and videos with fast flashing lights or sudden movement can trigger photosensitive epileptic seizures and migraines.
- Avoid posting this kind of media.
- If you must, mark the media as sensitive and add a content warning, for example "CW: flashing lights". On bolha.us this is mandatory, as rule 10 says.
Captions for videos and audio
If the video has speech, add captions or write a summary of what is said in the post itself. This helps deaf people and anyone who has the sound off at the moment.
2. Writing and formatting
Capitalise each word in hashtags
Write #DigitalAccessibility instead of #digitalaccessibility. With capitals, the screen reader
can tell the words apart. Without them, it tries to read everything as a single word and the result
is gibberish. Mastodon search ignores case, so the hashtag is found just the same.
Emojis in moderation
Screen readers read the name of every emoji. Three fire emojis in a row become "fire, fire, fire".
- Avoid several emojis in a row.
- Don't use emojis in place of words in the middle of a sentence.
- Prefer putting emojis at the end of the post.
- Use few or none in your display name: it is read every time someone hears one of your posts.
Don't use "fancy fonts"
Sites that generate "different" letters (bold, italic, cursive, circled letters) don't change the font. They swap the letters for mathematical symbols that only look like letters. Screen readers read these symbols one by one, or skip them all, and search can't find the word.
To highlight something, use real bold and italics: posts on bolha.us accept markdown.
Clear links
Say where the link goes before you add it. Instead of "click here: (link)", write something like "Read the full guide on the city website: (link)". Huge links in the middle of a sentence get in the way of reading aloud; leave the link at the end.
Post language
Check that the language chosen at the bottom right of the compose box matches the language you wrote in. Screen readers use it to pick the pronunciation, and it feeds automatic translation and other people's language filters. To avoid remembering every time, set your default language in the settings.
3. Content warnings (CW)
The CW button hides the text behind a warning, so each person decides whether, and when, to read it.
Use a CW for:
- spoilers of series, films, books and games;
- heavy topics, such as violence, death, abuse or mental health crises;
- media that flashes or has fast motion;
- very long texts, with a summary in the warning.
Say in the warning what it is about, for example "CW: Andor season 2 spoiler". A vague warning, like just "CW", doesn't help people decide.
The cases where a CW is mandatory on bolha.us are in rule 10. Politics doesn't need a CW here.
4. How to write a good description
The goal is to convey the same information, feeling or humour a sighted person gets from looking at the image, without wearing out the listener.
The basics: from the main point to the details
Start with what matters most, then add the details that help understand the scene. A good order is: who or what, doing what, where or in what context.
- Instead of: "My dog."
- Prefer: "Tan mixed-breed dog sprawled asleep on a blue sofa, one paw covering its eyes."
Rules that always apply
- Don't start with "Image of" or "Photo of". The screen reader already announces an image. But say the type when it matters: "Screenshot…", "Bar chart…", "Watercolour illustration…".
- Transcribe all visible text. In screenshots, memes, posters and comics, type the text word for word. If there is a dialogue, say who says what.
- Explain the joke. In memes, describe the expression or scene that makes it funny.
- Colours and style only when they matter: "red shirt", "black-and-white photo".
- Punctuate properly. Commas and full stops create the pauses when reading aloud.
- Don't repeat the post. The description complements the post text; it doesn't copy the caption.
What to include and what to avoid
| Include | Avoid |
|---|---|
| Actions and expressions: "man smiling", "cat curled up asleep". | Assumptions: "man happy because he won the lottery", unless the context makes it clear. |
| Colours and light that make a difference: "orange sky at sunset". | Irrelevant details, like every object in the background of a selfie. |
| People's characteristics when they are part of what the post is about. | Copying the post text into the description. |
Examples
Photo
- Instead of: "My dog."
- Prefer: "Close-up of a tan mixed-breed dog lying on the grass, looking at the camera with its tongue out."
Chat screenshot
- Instead of: "WhatsApp screenshot."
- Prefer: "Screenshot of a WhatsApp chat. Maria asks: 'Are you coming today?'. João replies with a sticker of a crying cat."
News
- Instead of: "Newspaper screenshot."
- Prefer: "Screenshot of a news story. The headline reads: 'New park opens this Sunday'. Below, an aerial photo of a wooded area with a walking track."
Meme
- Prefer: "'This is fine' meme. A cartoon dog in a hat drinks coffee at a table while the room burns around him. Speech bubble: 'This is fine'."
Chart
- Prefer: "Bar chart of the number of bolha.us accounts per year: 2022, one thousand accounts; 2023, five thousand; 2024, ten thousand."
The chart figures are just an example.
How long should it be
On bolha.us a description can be up to 10,000 characters (a post goes up to 2,400). For an ordinary photo, one to three short sentences are enough. Use the extra room for long screenshots, multi-panel comics and infographics. If an infographic is very complex, summarise it in the description and put the full data in the post, behind a CW if it gets long.
A little automatic help
descreve.bolha.us is bolha's image description bot. Mention @descreve@bolha.us in your post and it replies with a suggested description. It is a starting point: check that it got the context right and adjust what is needed.
5. Setting up Mastodon
These options are in the web version of bolha.us, in the browser on your computer or phone, under Preferences (the gear icon). The names below are the ones shown on screen with the interface in English.
Less motion and animation
In Preferences › Appearance, in the Animations and accessibility section:
- Check Reduce motion in animations: turns off transitions and sliding effects.
- Uncheck Auto-play animated GIFs: GIFs, avatars and animated emojis stay still until you hover or tap them.
- Check Slow mode if you'd rather the timeline didn't scroll on its own: new posts wait for a click to appear.
- Check Disable swiping motions if you browse on your phone and switch columns by accident.
Contrast and reading
Still in Preferences › Appearance, at the top of the page:
- In Contrast, choose High to increase the difference between text and background.
- In Color scheme, choose Light, Dark or Auto (follows your system).
- Check Use system's default font if your system font is more comfortable for you.
Sensitive media and content warnings
In Preferences › Appearance, in the Sensitive content section:
- In Media display, choose Default to hide media marked as sensitive, or Hide all to hide all media until you click.
- Leave Always expand posts marked with content warnings unchecked if you want to decide before reading each post with a CW.
Description reminder
In Preferences › Appearance, in the Advanced settings section, make sure Warn me before posting media without alt text is checked. With it, Mastodon asks before you post an image without a description.
Default post language
In Preferences › Posting defaults, under Posting language, choose the language you write in most. Your posts then go out with the right language for screen readers and automatic translation.
6. Before you post
- Does every image, GIF and video have a description?
- Are the hashtags
#WrittenLikeThis? - Are the emojis few and at the end?
- Does the topic call for a content warning?
- Is the post language right?
See also
- bolha.us rules: what applies on the instance, including image descriptions and content warnings.
- Tips for newcomers: your first steps on bolha.us.
- descreve.bolha.us: the bot that suggests descriptions for your images.
Found something to improve? This guide is open: the repository is MIT and suggestions are welcome at help@bolha.us.