5 ms·

If you feel like using asciinema or similar on your readme - please consider using plain text instead. This fancy players: - are unfriendly to visually impair

If you feel like using asciinema or similar on your readme - please consider using plain text instead. This fancy players: - are unfriendly to visually impaired people - are unfriendly to the many people with low bandwith in the global south - require you to watch the play instead of scanning through text with your eyes - cannot be searched for text strings easily - cannot be easily used in a terminal or without a browser

jimws 7y ago
Thank you for making this point. Plain text is really underappreciated. When I visit a project README, I don't want to wait for the entire replay. I just to skip to the part of the documentation that is relevant to me. A short asciinema replay can be useful for a quick demo buy don't let that substitute your text documentation. I may watch the replay only once but I will come back to a well written documentation again and again.
turtlequeue 7y ago
I am using asciinema there: https://github.com/turtlequeue/quickstart-js https://github.com/turtlequeue/quickstart-js I think it makes sense in this case because one terminal "speaks" to another. I agree with your assessment about plain text - do you think there is a good way to present this kind of workflow using plain text?
csdvrx 7y ago
Uploading ascii equivalents is a great idea! I usually do that, so I can later reconvert if needed. Can you tell me if your text browser/Braille reader works well with https://github.com/csdvrx/pg_csdvrx/blob/master/pg_csdvrx.ttyrecord https://github.com/csdvrx/pg_csdvrx/blob/master/pg_csdvrx.tt... ? This is my latest recording. I removed color and unicode to be more accessible but I still have some Ansi.
- masukomi 7y ago
  easy way to test if a web page sucks for blind people: Use Lynx[1] to browse it. It's not a perfect representation of what they experience but it's a very easy way to get a good impression. [1]: https://lynx.browser.org/ https://lynx.browser.org/
  - csdvrx 7y ago
    I was wondering more how well ttyplay was working on Braille terminals, or if they could easily edit ttyrec files.
awalton 7y ago
> please consider using plain text instead You do understand this is a false dichotomy? You can have both. Some people would rather watch a video and follow along, whereas others get more out of reading text... and both fit neatly on a page right next to one another.
- StavrosK 7y ago
  For double the effort, which not many people go to.
  - masukomi 7y ago
    sure, if you're going to be lazy and only do one do text. HOWEVER advocating for the lazy path amongst fellow practitioners is not a great strategy to promote quality output. Documentation is hard. Good documentation is harder. There are many occasions where video and video-like things are good for getting a feel for something and just plain text is good for reference. We shouldn't be saying "just use text because you probably won't bother doing everything you should". We should be saying "Hey, video, still images, and text all combine to make great documentation and help people to understand and use your tool / product." They take time, but we should care about our users, and thus we should take the time to support them.
  - nickcox 7y ago
    Not sure it's double the effort. Once you've written the textual version, you pretty much only need to copy and paste it into a terminal to produce the asciicast version. That's how I did the animations for this Powershell tool. https://github.com/nickcox/cd-extras https://github.com/nickcox/cd-extras

jimws 7y ago

Thank you for making this point. Plain text is really underappreciated. When I visit a project README, I don't want to wait for the entire replay. I just to skip to the part of the documentation that is relevant to me. A short asciinema replay can be useful for a quick demo buy don't let that substitute your text documentation. I may watch the replay only once but I will come back to a well written documentation again and again.

turtlequeue 7y ago

I am using asciinema there: https://github.com/turtlequeue/quickstart-js https://github.com/turtlequeue/quickstart-js I think it makes sense in this case because one terminal "speaks" to another. I agree with your assessment about plain text - do you think there is a good way to present this kind of workflow using plain text?

csdvrx 7y ago

Uploading ascii equivalents is a great idea! I usually do that, so I can later reconvert if needed. Can you tell me if your text browser/Braille reader works well with https://github.com/csdvrx/pg_csdvrx/blob/master/pg_csdvrx.ttyrecord https://github.com/csdvrx/pg_csdvrx/blob/master/pg_csdvrx.tt... ? This is my latest recording. I removed color and unicode to be more accessible but I still have some Ansi.

masukomi 7y ago
easy way to test if a web page sucks for blind people: Use Lynx[1] to browse it. It's not a perfect representation of what they experience but it's a very easy way to get a good impression. [1]: https://lynx.browser.org/ https://lynx.browser.org/
- csdvrx 7y ago
  I was wondering more how well ttyplay was working on Braille terminals, or if they could easily edit ttyrec files.

awalton 7y ago

> please consider using plain text instead You do understand this is a false dichotomy? You can have both. Some people would rather watch a video and follow along, whereas others get more out of reading text... and both fit neatly on a page right next to one another.

StavrosK 7y ago
For double the effort, which not many people go to.
- masukomi 7y ago
  sure, if you're going to be lazy and only do one do text. HOWEVER advocating for the lazy path amongst fellow practitioners is not a great strategy to promote quality output. Documentation is hard. Good documentation is harder. There are many occasions where video and video-like things are good for getting a feel for something and just plain text is good for reference. We shouldn't be saying "just use text because you probably won't bother doing everything you should". We should be saying "Hey, video, still images, and text all combine to make great documentation and help people to understand and use your tool / product." They take time, but we should care about our users, and thus we should take the time to support them.
- nickcox 7y ago
  Not sure it's double the effort. Once you've written the textual version, you pretty much only need to copy and paste it into a terminal to produce the asciicast version. That's how I did the animations for this Powershell tool. https://github.com/nickcox/cd-extras https://github.com/nickcox/cd-extras