Discussion: Fine-graining the Documentation Accessibility description.

[SMotaal]

This issue tracks discussions related to the Description section of the Documentation Accessibility draft.

## Description Documentation accessibility contains issues of technical accessibility as well as readability issues with the goal to foster understanding for the widest audience of potential contributors to the project. Users of documentation have different abilities, ways of accessing or consuming documentation, requiring it to be offered in different formats that would be equally empowering these different users’ points of view. Accessibility of documentation is critical due to the role documentation plays in open source projects. Documentation is codified knowledge across various dimensions of an open source project. Documentation on the processes and practices of the community empowers participants to contribute with certainty for how and why things are happening. It may also be on the artifacts produced by the community and as such empower participants to know where to contribute and what kind of contributions further the goals of the community.

---

Documentation accessibility contains issues of technical accessibility as well as readability issues with the goal to foster understanding `for the widest audience of potential contributors to the project`¹`, without disproportionately contributing to or offsetting artificial debts on certain segments of its intended audience`²`, without disproportionately creating or perpetuating artificial debts on certain segments of its intended audiences`³`. Users of documentation have different abilities, ways of accessing or consuming documentation, requiring it to be offered in different formats that would be equally empowering these different users’ points of view`⁴. Accessibility of documentation is critical due to the role documentation plays in open source projects. Documentation is codified knowledge across various dimensions of an open source project.

1. `for the widest audience of potential contributors to the project` > **Note** — This is very common verbiage for most projects today. 2. `, without disproportionately contributing to or offsetting artificial debts on certain segments of its intended audience` > @jlovejoy: > > I'd keep positive framing for this thing - it's more salient that way. > @SMotaal: > > Unfortunately my problem has been positive framing === systematic filtering, can we please find a way to not delete this. > @jlovejoy: > > I think my issue was with the use of "contributing" - it is correct, but I want to save it for "contributing to the project" type references! 3. `, without disproportionately creating or perpetuating artificial debts on certain segments of its intended audiences` > **Note** — This is the often glossed over reality that becomes immutable when someone tries to point out why documentation is actually "disabling" that way… most sadly resign to giving up, and we end up we folks thinking that they are accessible and it was just individual incompetence validated by opting for self-exclusion (ie retreat). 4. `. Users of documentation have different abilities, ways of accessing or consuming documentation, requiring it to be offered in different formats that would be equally empowering these different users’ points of view` > @GeorgLink: > > this attempts to clarify that documentation needs to be tailored to the specific needs of different types of users.

---

Google Document

[SMotaal]

@jlovejoy, I do apologize, but the comments in the doc got too crowded… hope you don't mind discussing this here!

Note — for visibility, if it was just the subtle change, please mention this here and we can close this issue and clean up the noise in the doc :)

[jlovejoy]

I think we may have mostly resolved this in the doc??

[GeorgLink]

I believe we resolved it today.

[SMotaal]

Aside — Can we leave at least 24 hours open in the future (re dwelling thoughts please).

---

So after dwelling (sleep to let my brain think :wink:) on yesterdays tailend discussion about documentation accessibility, am afraid I am hitting my miscommunication threshold because of the long journey of stress related to displacements of artificial debts.

The term "artificial debts" came to mind one day when people who developed widely popular frameworks started mistaking try {} catch {} and if {} else {} logic and now when you did something they imagined you do they gave you custom error messages… but if you did not think like them, they threw a completely wrong one.

Digging further into the problem, made me realize, they are throwing errors when the runtime itself completely supported your code… as in, code without framework works, and without changing one line, even with it being decoupled from the framework, they have designed their pipelines to eagerly throw errors and never considered the maintenance cost they could not spare to realign as the web platform evolved… hence artificial debt, on them, and someone like me who follows the specs.

And if filing issues where you would want the human touch to find resolve from being artificially dismissed by code, if communication difference was not sadly treated with a 10-foot-pole, then those issues would not become ones I literally end up taking offline 😉

---

So let's see a real-world example about accessibility, but please, do not just take a glance, this does not work if you do not try to operate with the urgency and sense of despair one might feel if they cannot play because they are always given the broken controller — and yes here it helps to think, they lived a life learning how to play with two left thumbs and any decent controller!

I've spent a very long time slowly figuring out how GitHub is positioning its accessibility runaround… and determined they are publicly disclosing their commitments and obligations. So I decided based on our meeting yesterday to start another one of those inhumane and offensive efforts (aka mind-melts) where it becomes too stressful to continue to try to remember that people are nice, even when the world is telling me but not to someone like me… https://github.com/SMotaal/a11y/issues/7

And just for context, visual and cognitive difference is separate from psychiatric disorders… but to be fair, runaround is not, if keeps happening in every direction, and in ways that make sure that mainstream does not see enough to empathise with the reality — move along people, nothing to see here, just poor folks struggling to deal with their misfortune!

Let's see how they fair between now and next meeting… I knew this was coming, just wanted to be sure the time is right.