FAQ - Use ZAP with a screenreader

[psiinon]

C/o https://twitter.com/zersiax/status/1366818505274908676
Original is https://www.dropbox.com/s/na61sia1se31xru/zap%20SR%20docs.md?dl=0 - I've made a few minor edits but otherwise its nearly word for work.
Although it does mention the HUD I've put it under the "Desktop UI" section and have not said its Windows specific.
I've asked the author in the above thread about its applicability to other OSs so we should probably wait for his reply before merging with that change.

Signed-off-by: Simon Bennetts [email protected]

[zersiax]

These instructions are specifically for Windows and, to some degree, even screenreader-specific. Java Swing UIs vary wildly in their "quirks" for screenreader users, I'd have to go in with VoiceOver for OS X and Orca on Linux to see what oddities I find and if it even works at all.
Swing long ago decided to do their own thing accessibility-wise rather than adhere to the already existing OS-specific accessibility stacks that were already in place, and while that means it should be accessible everywhere in theory, in practice it just means screenreaders support that particular brand of telling them what to say to varying degrees.
A super small example is that I refer to using tab navigation within most ZAP windows. On OS X you practically never tab navigate through UIs as it rarely works well; you use VoiceOver commands, and I have no idea if those work well in the ZAP UI yet.
Some of these findings, particularly the ones on the HUD, will likely change / get better or worse as the project further develops anyway, so I can always just make separate Prs if:

• Bugs get fixed that render some of the points discussed here no longer applicable;
• I learn more about other operating systems.

In my experience though, I would say that Windows with NVDA the way I've described it so far will very likely be the happy path, as that combination gives the most breathing room in terms of the amount of different things you can do in order to make an uncooperative application work well.

[thc202]

it's → its, I didn't check all text yet (there might be other typos).

[kingthorin]

Good catch

.

[kingthorin]

Suggested change

	If you cannot tab from this point onwards, alt+tab out and back into the application. You should land on the " safe mode" toolbar button.
	If you cannot tab from this point onwards, alt+tab out and back into the application. You should land on the "safe mode" toolbar button.

[kingthorin]

Suggested change

	At present, the HUD works reasonably well if you stay in browse mode. Hitting enter on the various graphics will toggle them or interact with them, we recommend going through the HUD tutorial to learn how most things work. The tutorial will refer to the images' contents, their filenames are reasonably clear on what they contain, use that to your advantage.
	At present, the HUD works reasonably well if you stay in browse mode. Hitting enter on the various graphics will toggle them or interact with them, we recommend going through the HUD tutorial to learn how most things work. The tutorial will refer to the images' contents, their filenames are reasonably clear on what they contain, use that to your advantage.

[kingthorin]

Suggested change

	- To check the status of the scope tool, break tool etc. look at the text right below the graphic in browse mode. This text will reflect it's current state (on/off, in/out etc.).
	- To check the status of the scope tool, break tool etc. look at the text right below the graphic in browse mode. This text will reflect its current state (on/off, in/out etc.).

[zersiax]

Just did some testing with Orca (Linux screenreader). While the very basics kinda work, anything involved quickly runs off the rails because the screenreader-specific cursors (to get places tab can't get you to) just flat out do not work in applications like this. So ... in a pinch I guess you can get as far as starting a Manual Explore session, but I would discourage people from doing this unless they really don't have any other options left.

[kingthorin]

@psiinon do you plan to finish this?

[psiinon]

In theory yes, but it looks like it needs a significant rewrite :/