Docs Volunteer

[blinding-pixels]

AccessKit Team, my name is Eshaan Sood. I am a blind developer. I came across your project while doing accessibility research and saw your requirement for docs. I would be more than happy to take this on systematically. If you could let me know what to start with I can start creating some documentation.

[DataTriny]

Hello @blinding-pixels, thank you for the offer.

Systematically documenting the project is something we have staarted together with @PoignardAzur but I always find a higher priority, so help would be much appreciated. However this require deep understanding of the subject. A good starting point for you could be to study the changes in #732 then dig into the code. Is there enough or too much information? Does it help you navigate the project and find the key pieces? Can you spot wording issues? Other improvements? Doing code reviews is a great way to jump into a new project and the linked pull request would be particularly useful to you.

There are many tasks you could handle after that, but I would prefer if you started with this.

How does that sound?

[blinding-pixels]

Sounds great. I have reviewed the architecture.md and have some usable findings. Would you like me to leave a comment on the PR itself?

[DataTriny]

Yes please. As a new joiner, your point of view on this document is very valuable.

[PoignardAzur]

See also #749.

Overall, most of AccessKit is pretty close to the ARIA spec, though we don't guarantee conformance. If you want to do systematic doc improvements, documenting the correspondence between AccessKit and ARIA would be helpful.

Basically, for each role, property, etc, we want to:

• Explain what the role/property/etc means.
• Link to its equivalent ARIA item, if any.
• Explain the differences with the ARIA version, if any.

Arnold and I were also considering adding some semi-structured spec document to serve as the source of truth for all documentation, but that's a longer-term concern.

[DataTriny]

I have actually started this specification, but one thing make this difficult: ARIA defines for each property whether it is required, recommended, optional or not applicable, for all roles. This distinction somewhat exist in AccessKit but it's not consistent and most often not even enforced.

[PoignardAzur]

I have actually started this specification

Nice!

Just to be clear, I want to reiterate, everything I mentioned in my previous post can be done without deciding on a spec.