@Michael Thanks for sharing this! This is really interesting!

My first impression is that in its current form, this is a solid, well-written piece of technical documentation which would be more appropriate for MediaWiki.org and not the best fit for the Technical blog (yet).

However, I do think that the topic of accessibility and screen readers is compelling and would be of interest to the audience of the technical blog -- so this has the potential to be a good fit for the blog with a little more context. Would you consider working on a piece that discussed more generally the why and how of accessibility and screen readers as an introduction to Orca?

Some questions you might answer are:

• Why should developers be thinking about accessibility?
• What are screen readers, what purpose do they serve, and why developers should incorporate them?
• Why Orca is a good choice for people working on Wikimedia projects, etc.

Then with that as context, we could link to the technical documentation on the topic, so people can read the Orca documentation on MediaWiki.org.

Let me know how that sounds to you and if there's anything I can do to support you.

(Personally this also makes me wonder if there is anything to improve on https://help.gnome.org/users/orca/stable/ - happy to push some patches there.)

In T251164#6086277, @srodlund wrote:

However, I do think that the topic of accessibility and screen readers is compelling and would be of interest to the audience of the technical blog -- so this has the potential to be a good fit for the blog with a little more context. Would you consider working on a piece that discussed more generally the why and how of accessibility and screen readers as an introduction to Orca?

I'm unsure that I'm the right person to write such an article as that seems to be outside of my domain of knowledge/expertise. Someone who actually uses a screen reader on a daily basis might be better suited for it.
Also, the article that you are describing seems to fall more into the category of Explainer for complicated tech concept or process, whereas I intended to write a Technical how-to type of article.

Some questions you might answer are:

• Why should developers be thinking about accessibility?
• What are screen readers, what purpose do they serve, and why developers should incorporate them?
• Why Orca is a good choice for people working on Wikimedia projects, etc.

I can expand the intro of the current article to talk a bit more about these points. Though, some oversight on the object level would be nice.

Then with that as context, we could link to the technical documentation on the topic, so people can read the Orca documentation on MediaWiki.org.

I'm not really sure that the current article is actually good documentation rather than a "Getting Started" tutorial for a specific secondary user group. For comprehensive documentation, it might be better to link directly to the official Orca docs by Gnome.

In T251164#6086692, @Aklapper wrote:

(Personally this also makes me wonder if there is anything to improve on https://help.gnome.org/users/orca/stable/ - happy to push some patches there.)

Not really for me. The only thing (and that is not even directly about Orca) is about how to use different voices with it - other than espeak-ng, because that voice sounds very artificial by today's standards. However, it might very well be that the answer to that is "Using other voices is not possible.".

@Michael So sorry! I missed the notification for your response when it came through. I think we can go with this as a Technical How-To if you can expand on those questions for the introduction. I'm also happy to review/edit and suggest places in the text where a little more information or context might be needed.

It's can sometimes be hard to pinpoint what separates functional technical documentation from a how-to for the blog post. Maybe the best way to think about it is thinking about the audience. Technical documentation would be for people who already know about Orca and want to use it -- so all they really need are instructions with minimal context. While folks reading a How-To Technical post may not yet know what Orca is or why they would want to implement it <-- providing a few more details can be really helpful for them.

I think if the introduction is expanded a bit more, then the instructions you created will fit well within the post and then we can link out to the official docs for folks who really want to explore.

Let me know how you would like to proceed. If you want to make some additions to your page on MediaWiki, and once that's done, I can add some comments inline.

I also forgot to address the markup in my last response. I will try and format this is a few ways and share screenshots here so you can see what it could look like on the published blog.

Heja @Michael and everybody! As a curious outsider I'm going to boldly jump in and...

1. ...propose to rephrase the intro a little bit:

<✄>
Modern websites are expected to be accessible for as many users as possible. Universal design includes aspects such as color contrast, keyboard navigation, or input methods. Blind users and users with visual impairments often also use screen reader software which renders text and images as speech or Braille output.
Hence developers need to design and implement websites that work well with assistive technology such as screen readers. The best way to ensure this is to actually use a screen reader yourself.

This tutorial covers how to install, set up and use Orca on Linux systems, with developers, product managers, and user experience designers in mind.
Orca is a screen reader available on Linux which is being continuously developed as part of the GNOME project. It is probably the best choice to test screen reader conformance when developing on Linux.

In addition to this tutorial, I also found a video with Orca installation, setup and usage instructions on Youtube for those who prefer a video format.
</✄>

2. I'm a bit torn whether to have distro-specific install instructions. A while ago I edited the Gerrit tutorial which had had install commands for ten distros. Maybe it's enough to state that people should install the orca and espeak-ng packages provided by their distribution? (Same package names on Fedora and Ubuntu.)

3. Towards the end I know how to use Orca (thanks!) but what are the consequences I should draw / actions to perform? (I assume if I cannot navigate to an element, or if an element does not have any output that I should fix something?) Could link to https://www.mediawiki.org/wiki/Accessibility_guide_for_developers ?

Hope this ^ is helpful input. Thanks for this tutorial! (Hope it'll also get linked from https://www.mediawiki.org/wiki/Accessibility_guide_for_developers ?)

Hey, thank you both for looking into this. I really appreciate it :).

I will extend the intro as you suggest and ping you both again when I'm done.

I finally implemented your suggestions, @Aklapper. Thank you again so much for helping out with this!

I have one questions about a single word that my first version included (and still does), but your suggestions do not:

This tutorial covers how to install, set up and use Orca on Linux systems, with sighted developers, product managers, and user experience designers in mind.

What I like to communicate with this is that I'm merely writing down my own experiences and don't want to presume the competence to write such a tutorial for people who actually have to use a screen reader in their day-to-day. Similarly, the suggestions to use a blindfold to explore one's product with a screenreader wouldn't feel appropriate for such an audience.

Yet, I'm not a native speaker and I'm not sure if that word actually works in communicating that? Or would maybe an extra short paragraph narrating my own background in writing this work better?

@Michael I think that word works well and conveys your meaning about who the tutorial is meant for. :-) I don't think an extra paragraph is necessary.

In T251164#6249494, @srodlund wrote:

@Michael I think that word works well and conveys your meaning about who the tutorial is meant for. :-) I don't think an extra paragraph is necessary.

That's great, thank you :-). From my side, this article would now be ready (unless I missed something). What are the next steps?

@Michael this looks good! I can move it over to the blog to prepare for posting.

I know there is some special formatting for the code and commands in the post, so once I have it formatted to the blog, I'll send you a preview image, so you can see how it will display.

Do you have an image you would like to use for the featured image? You can choose one or I can choose one on your behalf. Here is some information about the use of images on the blog: https://www.mediawiki.org/wiki/Wikimedia_technical_blog_editorial_guidelines#Images_used_in_your_post

Once these steps are done, I can schedule the post to publish later this week!

@Michael here is a screenshot of how the different kinds of text are rendering and how they will look in the published blog post. Let me know if this works for you. If not, I can attempt to do some alternate formatting (though I can't garuntee it will work given I don't have full contol over how the blog displays text).

@srodlund Thank you for looking into this!

The text looks ok. Optionally, it could be a bit better as described in the last bullet point of the description of this task, but that might non-trivial to achieve. I do not know WordPress good enough to give specific suggestions.

On the Gnome help-page, they used the following CSS

kbd {
    font-family: inherit;
    font-size: inherit;
    color: #2e3436;
    background-color: #f3f3f0;
    border: solid 1px #babdb6;
    -moz-border-radius: 2px;
    -webkit-border-radius: 2px;
    border-radius: 2px;
    -moz-box-shadow: 1px 1px 2px #babdb6;
    -webkit-box-shadow: 1px 1px 2px #babdb6;
    box-shadow: 1px 1px 2px #babdb6;
    margin: 0 0.2em 0 0.2em;
    padding: 0 0.5em 0 0.5em;
    white-space: nowrap;
}

to make it look like this:

But if that is not possible, then the status quo is ok as well. The keys are sufficiently set-apart from the rest of the text to be understandable. :)

About the image:
I think you are much better skilled than me at choosing a suitable image for this blog post. I'm sure whatever image you come up with is fine by me :)

Thanks, @Michael ! I'll experiment with the CSS and see if it's possible given our Wordpress installation. In either case, my plan is to publish this on 2 July 2020. I'll leave a note here when it is up!

@Michael This has been published! https://techblog.wikimedia.org/2020/07/02/an-orca-screen-reader-tutorial/ I think it looks really good! Thanks for contributing!

In T251164#6275506, @srodlund wrote:

@Michael This has been published! https://techblog.wikimedia.org/2020/07/02/an-orca-screen-reader-tutorial/ I think it looks really good! Thanks for contributing!

I like it! Thank you for making this happen 🙂