3 ms·

Screen reader user here. Please don't do this. There are blind developers out there. Don't make their life hell. Often those diagrams are a good excuse not to w

Screen reader user here. Please don't do this. There are blind developers out there. Don't make their life hell. Often those diagrams are a good excuse not to write a good description of what the system really does. If you absolutely must, please ensure there's a text description that provides exactly as much info as the diagram (or more). If you can, use formats like graphvis and include the text the graphs were generated from, it's at least somewhat readable. The way sourcegraph[0] used to do this was IMO acceptable. They had a graph but if you wanted to, you could sort of figure out what the grah looks like by reading it's text. They also had a good description of what the system does directly below. sadly, They're a bit worse now, though the source is still available if you dig deep enough. [1] [0] https://github.com/sourcegraph/sourcegraph/blob/2.13.0/doc/dev/architecture.md https://github.com/sourcegraph/sourcegraph/blob/2.13.0/doc/d... [1] https://github.com/sourcegraph/sourcegraph/blob/master/doc/dev/img/architecture.mermaid https://github.com/sourcegraph/sourcegraph/blob/master/doc/d...

sqs 8y ago
Sourcegraph CEO here. Thank you for pointing out that the way we embed our architecture diagram was better before for screen reader users. Sorry for the regression. I filed an issue at https://github.com/sourcegraph/sourcegraph/issues/2355 https://github.com/sourcegraph/sourcegraph/issues/2355 for us to include a link to the diagram's Mermaid source definition so you don't need to dig around for it. Note: For anyone else interested, you can read the architecture doc mentioned in the parent comment at https://docs.sourcegraph.com/dev/architecture https://docs.sourcegraph.com/dev/architecture. BTW, it would be awesome for someone to build a Sourcegraph extension (https://docs.sourcegraph.com/extensions https://docs.sourcegraph.com/extensions) that renders Mermaid/Graphviz diagrams in code. Then you could see the rendered graphs when browsing on GitHub if you use our Chrome/Firefox browser extensions (https://docs.sourcegraph.com/integration/browser_extension https://docs.sourcegraph.com/integration/browser_extension).
KayEss 8y ago
We're experimenting with Mermaid diagrams <https://mermaidjs.github.io/> https://mermaidjs.github.io/> in our source code. How does that come across?
- miki123211 8y ago
  I assume that as a reader of the code, I can get to the code behind those diagrams, not just the images? If yes, I would call it acceptable. Not something I'd prefer personally, but that's a good trade off between actually making an illustration for the sigted and making something accessible to everyone. Accessibility must be taken into consideration, but it shouldn't dominate the software and make the experience worse for users who don't need it. I think you strike the balance here.

sqs 8y ago

Sourcegraph CEO here. Thank you for pointing out that the way we embed our architecture diagram was better before for screen reader users. Sorry for the regression. I filed an issue at https://github.com/sourcegraph/sourcegraph/issues/2355 https://github.com/sourcegraph/sourcegraph/issues/2355 for us to include a link to the diagram's Mermaid source definition so you don't need to dig around for it. Note: For anyone else interested, you can read the architecture doc mentioned in the parent comment at https://docs.sourcegraph.com/dev/architecture https://docs.sourcegraph.com/dev/architecture. BTW, it would be awesome for someone to build a Sourcegraph extension (https://docs.sourcegraph.com/extensions https://docs.sourcegraph.com/extensions) that renders Mermaid/Graphviz diagrams in code. Then you could see the rendered graphs when browsing on GitHub if you use our Chrome/Firefox browser extensions (https://docs.sourcegraph.com/integration/browser_extension https://docs.sourcegraph.com/integration/browser_extension).

KayEss 8y ago

We're experimenting with Mermaid diagrams <https://mermaidjs.github.io/> https://mermaidjs.github.io/> in our source code. How does that come across?

miki123211 8y ago
I assume that as a reader of the code, I can get to the code behind those diagrams, not just the images? If yes, I would call it acceptable. Not something I'd prefer personally, but that's a good trade off between actually making an illustration for the sigted and making something accessible to everyone. Accessibility must be taken into consideration, but it shouldn't dominate the software and make the experience worse for users who don't need it. I think you strike the balance here.