Connect with us

Tech

Best Practices for Inclusive CIs

Published

on

Best Practices for Inclusive CIs

This began as a reply to another article by Lucas F. Costa; it lists practices to improve user-experience (UX) of command-line interfaces (CLIs). It is a solid piece of advice. I like the advice about input validation and understanding errors. Some of its suggestions, especially from an accessibility standpoint, are however problematic.

Note: this article specifically concerns CLIs, not full-blown textual user interfaces (TUIs). This article focuses on utilities that work with UNIX-like shells. Other command-line environments might have different conventions.

Problematic patterns


Permalink to section

The “Getting Started Experience” section of Lucas’ article has a GIF video of a CLI utility printing --help output, featuring a decorative border.

Code snippet 1 (console):
Lucas’ article leads with an example –help output that’s surrounded by a decorative textual border. This is a transcription, but it’s wrapped in a smaller width.
$ tool --help

+ Getting started ----------------------------------------+
|                                                         |
  To scaffold a new project, run:                        
|                                                         |
    $ mytool init                             
|                                                         |
  If you already have a project set up and would like to 
  add, remove, or update its structure, run:             
|                                                         |
    $ mytool manage                                      
|                                                         |
+---------------------------------------------------------+

Use: Tool [options].
Commands:
Tool init [directory] creates new projects
Tool manage lets you manage an existing project

Options:
Help [boolean]
  --version	Show version number	[boolean] 
  1. Borders within TUIs should always use characters that are specifically designed for textual interfaces, such as boxdraw characters. Although I believe the GIF did follow this advice, it is worth stating it. These can be decoded by accessible terminal emulators and incorporated into their reports via an accessibility API. However, breaking down these boundaries with descriptive text can make detection of readable texts error-prone.

  2. Borders are to be used sparingly as they can cause problems when the window is resized. note 1 Re-sizing terminal windows is quite common: think about the combined user-base of tiling window managers, tiling terminal session managers (Tmux, Screen, etc. Multiplexing terminal emulators and simple split-windows are all possible.

  3. Decorative content in CLI output should be limited, since the output of CLI utilities can be piped through other programs. These tools should at the minimum be able detect if their standard output has been redirected or piped, and then sanitize it accordingly.

The “Colours Emojis and Layouting” section has similar issues.

  1. Nearly all animated spinners pose a problem for screenreaders. It is better to have a simple progress meter, numeric percentage and flags to enable/disable them.

  2. An excessive amount of animation and color can cause problems for users with attention or vestibular disorders and others on the autism spectrum. Many tools offer a --color[=WHEN] flag where WHEN is always, never, or auto. Expecting users to learn all the color configurations for all their tools is unrealistic; tools should respect the NO_COLOR environment variable.

Recommendations


Permalink to section

This is a non-exhaustive list of simple, baseline recommendations for designing CLI utilities.

  1. Send your tool’s output through a program like espeak-ng and listen to it. Is it possible to make sense of the output?

  2. How unique is your tool’s output. To reduce learning curve, output should be as similar as possible to other utilities. It should be boring.

  3. Refer to the latest WCAG publication (currently WCAG 2.2) and take a look at the applicable criteria. Many have accompanying techniques for plain-text interfaces.. The WCAG offers two examples of recommendations: avoid relying on color and use whitespace and/or insertation for pseudo-headings.

  4. Write manpages! Man pages have a standardized,note 2 predictable, searchable format. Screen-readers often have scripts that make it easier to read man pages. For those who prefer web-based documentation, a man page can also be converted to HTML easily. note 3 If your utility has a config file with special syntax or vocabulary, write a dedicated man page for it in section 5 and mention it in a “SEE ALSO” section. note 4

  5. Add shell completions to your program so that users can tab-complete options. This is particularly helpful in shells like Zsh that support help-text in tab completions, especially when combined with plugins like fzf-tab that enable fuzzy-searching help-text (see code snippet 2).

  6. Related. 5: use a well-understood format for -h and --help output. This makes it much easier to generate shell completions. You can also delegate both generation to a library following this advice.

  7. Follow convention: Use POSIX-like options. If your tool contains a lot of options, you might consider supplementing them by GNU-style long options. note 5

  8. You can either delegate output wrapping and the terminal or detect how many columns you want to output. If you have the option, prefer the first one, especially if the output is not a TTY.

  9. Make sure that your web-based documentation is accessible or that the forge frontends you use are mirrored in a location with good accessibility. Although I admire the work of Gitea, their web frontend is plagued with critical issues. note 6 For now, if your forge has accessibility issues, mirroring to GitHub and/or Sourcehut seems like a good option.

  10. Avoid breaking changes to your program’s CLI. It is an API. Unless documentation states otherwise, argument parsing in it is an API. note 7 Semantic versioning is your friend.

  11. Be predictable. Users expect git log to print a commit log. Users do not expect git log to make network connections, write something to their filesystem, etc. You should only do the minimum functionality requested by the command. This disqualifies opt out telemetry.

Code snippet 2 (console):
This is what tab-completion for MOAC looks like with fzf-tab.
$ moac -
> -p
  9/11 (0)
-P -- Power available to the computer (W).
> -p -- Password to analyze
  -s  -- password entropy
-h -- Display this help message
-r -- Interactively type a password into the terminal; overrides are -p
-T -- Temperature of the system (K).
-m -- Mass at the attacker's disposal (kg).
  -q  -- account for quantum computers using Grover's algorithm

More opinionated considerations

These considerations are more subjective and debatable than the recommendations before them, and should be treated with skepticism. This section is called “considerations” and not “recommendations”. There are exceptions; I am not here to make decisions for you.

  1. Remember that users aren’t always at their best when they read --help output; they could be trying to solve a frustrating problem, feeling a great deal of anxiety. Keep the output clean, predictable, boring, and fast. A 2-second delay and spinning fans will probably be extremely unpleasant for already-stressed users, especially if they need to use it often. note 8

  2. Include an example usage in your man pages. Consider submitting the example usage to the tldr pages project if your tool gets popular.

  3. Include a list of examples command invocations as well as expected output. Double the document as a test suite. My moac testdata and moac-pwgen testdata scripts are good examples. This can be used to verify API stability and as documentation.

  4. Make your man pages as similar as other man pages on target OS. Many programs can parse man pages and expect them follow a consistent structure. Test your man pages with multiple programs. This is similar to how Web pages are tested in different browser engines. w3mman (included in w3m) is a good example to make sure auto-hyperlinking works. Pandoc is another tool worth trying.

  5. Refer to similar tools. If you’re using Rust to make a fast alternative to popular coreutils: model its behavior, help-text, and man pages after ripgrep and fd. If you’re making a linter for Go: copy go vet.

  6. If you want your tool to be simple, make it readable to humans and machines. It should work when sent to another program’s standard input or when parsed by an individual. This is particularly useful for people who redirect output streams to log file.

  7. Consider splitting related functionality among many executables (the UNIX method) and/or subcommands (like Git). I split MOAC’s functionality across both moac and moac-pwgen, and gave moac three subcommands. The “Consistent commands trees” section of Lucas’ article has good advice.

  8. Do not confuse CLIs with TUIs. A CLI should not be interactive; a TUI should. There are exceptions for very simple interfaces (e.g. Magic-Wormhole, and other similar programs, accept input from users. However, as interface complexity increases, you might consider splitting the program into two sibling applications, where one can have a non-interactive, “pure” CLI.

  9. Go above and beyond by writing separate integrations for environments like Emacspeak. note 9

Name conflicts


Permalink to section

This section might be the most important part of this post. Packagers might have to rename executables that are in conflict with binary names. Otherwise, users will have to juggle $PATH overrides. note 10

Before publishing your software, check for binary name conflicts. Many package managers include functionality that allows you to search for packages files. To test for conflicts, I recommend this with large repositories.

Code snippet 3 (console):
DNF is the best way to query package contents on Fedora or derivatives. You can also check cht.sh for other common commands.
$ dnf provides /usr/bin/p
Last metadata expiration check: 0: 48: 19 ago [...]
perl-App-p-0. 0400-19.fc36.noarch : Steroids for your perl one-liners
Repo        : fedora
From:
Filename: /usr/bin/p

$ curl https://cht.sh/fly
# Fly
# Command-line tool to use for concourse-ci.
# More Information:
[...]

Thanks to Emily for reminding me of name conflicts.

References and further reading


Permalink to section

  1. Harini Sampath, Alice Merrick, and Andrew Macvean. 2021. . In CHI Conference on Human Factors in Computing Systems (CHI ’21), May 8-13, 2021, Yokohama, Japan. ACM, New York, NY, USA 10 Pages. DOI 10.1145/3411764. 3445544

  2. . Alastair Campbell, Michael Cooper, Andrew Kirkpatrick. W3C. .

  3. . Aanand Prasad and Ben Firshman are the other members of the team. Commit 89d755c, .


Footnotes

  1. Yes. It is possible to support resizing using a TUI library such as ncurses. TUIs are not covered in this article. I will be concentrating on CLIs.

  2. Well, they’re somewhat standardized compared to plain stdout.

  3. My other article on accessible textual websites is probably relevant when it comes to Web-based documentation

  4. For more on man page sections, see the man(1) man page.

  5. I need to take my own advice for programs like moac. Ugh.

  6. See this Fediverse thread about forge accessibility.

  7. For a good example, Git distinguishes between regular output and porcelain friendly output. Both the instability and stability of the former are clearly documented in Git man pages as well as in the official Git Book.

  8. The slow responses to basic flags like --help is one of many reasons I dislike Java command-line utilities (signal-cli, Nu HTML Checker). This is something I think I am not the only one saying.

  9. I used to not-very-seriously claim that Neovim, my preferred $EDITOR, is better than Emacs. After I tried Emacspeak, I changed my mind. I made the same claim but softly, and with an exception for Emacspeak.

  10. Executables that may conflict with other executables are a notable exception. Fedora, Debian and derivatives all have an “alternatives” system that manages these overrides via symlinks. Examples include toolchains (cc and ld could point to their GCC or Clang implementations) and mail transfer agents (sendmail and mta have been re-implemented many times over).

Read More

Continue Reading
Click to comment

Leave a Reply

Your email address will not be published.

Tech

Nothing announces official launch date for new Ear (stick) AirPods alternatives

Published

on

By

Nothing announces official launch date for new Ear (stick) AirPods alternatives
Nothing Ear (stick) held by a model on white background



(Image credit: Nothing )

True to form, Nothing has just announced the full reveal date for its upcoming audio product, Ear (stick). 

So, an announcement about an announcement. You’ve got to hand it to Carl Pei’s marketing department, they never miss a trick.

What we’re saying is that although we still have ‘nothing’ conclusive about the features, pricing or release date for the Ear (stick) except an image of another model holding them (and we’ve seen plenty of those traipsing down the catwalk recently), we do have a date – the day when we’ll be granted official access to this information. 

That day is October 26. Nothing assures us that on this day we’ll be able to find out everything, including pricing and product specifications, during the online Ear (stick) Reveal, at 3PM BST (which is 10AM ET, or 1AM on Wednesday if you’re in Sydney, Australia) on nothing.tech (opens in new tab)

Any further information? A little. Nothing calls the Ear (stick), which is now the product’s official name, “the next generation of Nothing sound technology”, and its “most advanced audio product yet”. 

But that’s not all! Apparently, Ear (stick) are “half in-ear true wireless earbuds that balance supreme comfort with exceptional sound, made not to be felt when in use. They’re feather-light with an ergonomic design that’s moulded to your ears. Delivered in a unique charging case, inspired by classic cosmetic silhouettes, and compactly formed to simply glide into pockets.” 

Opinion: I need more than a lipstick-style case

Nothing Ear (stick) – official leaked renders pic.twitter.com/FrhKmRttmiOctober 1, 2022

See more

It’s no secret that I want Nothing’s earbuds to succeed in world dominated by AirPods; who doesn’t love a plucky, eccentric underdog? 

But in order to become some of the best true wireless earbuds on the market, there is room for improvement over the Nothing Ear 1, the company’s inaugural earbuds. 

Aside from this official ‘news’ from Nothing, leaked images and videos of the Ear (stick) have been springing up all over the internet (thank you, developer Kuba Wojciechowski) and they depict earbuds that look largely unchanged, which is a shame. 

For me, the focus needs to shift from gimmicks such as a cylindrical case with a red section at the end which twists up like a lipstick. Don’t get me wrong, I love a bit of theater, but only if the sound coming from the earbuds themselves is top dog. 

As the natural companions for the Nothing Phone 1, it makes sense for the Ear (stick) to take a place similar to that of Apple’s AirPods 3, where the flagship Ear (1) sit alongside the AirPods Pro 2 as a flagship offering. 

See, that lipstick case shape likely will not support wireless charging. That and the rumored lack of ANC means the Ear (stick) is probably arriving as the more affordable option in Nothing’s ouevre. 

For now, we sit tight until October 26. 

Becky is a senior staff writer at TechRadar (which she has been assured refers to expertise rather than age) focusing on all things audio. Before joining the team, she spent three years at What Hi-Fi? testing and reviewing everything from wallet-friendly wireless earbuds to huge high-end sound systems. Prior to gaining her MA in Journalism in 2018, Becky freelanced as an arts critic alongside a 22-year career as a professional dancer and aerialist – any love of dance starts with a love of music. Becky has previously contributed to Stuff, FourFourTwo and The Stage. When not writing, she can still be found throwing shapes in a dance studio, these days with varying degrees of success.  

Read More

Continue Reading

Tech

YouTube could make 4K videos exclusive to Premium subscribers

Published

on

By

YouTube could make 4K videos exclusive to Premium subscribers
Woman watching YouTube on mobile phone screen



(Image credit: Shutterstock / Kicking Studio)

You might soon have to buy YouTube Premium to watch 4K YouTube videos, a new user test suggests.

According to a Reddit thread (opens in new tab) highlighted on Twitter by leaker Alvin (opens in new tab), several non-Premium YouTube users have reported seeing 4K resolution (and higher) video options limited to YouTube Premium subscribers on their iOS devices. For these individuals, videos are currently only available to stream in up to 1440p (QHD) resolution.

The apparent experiment only seems to be affecting a handful of YouTube users for now, but it suggests owner Google is toying with the idea of implementing a site-wide paywall for access to high-quality video in the future.

So, after testing up to 12 ads on YouTube for non-Premium users, now some users reported that they also have to get a Premium account just to watch videos in 4K. pic.twitter.com/jJodoAxeDpOctober 1, 2022

See more

It’s no secret that Google has been searching for new ways to monetize its YouTube platform in recent months. In September, the company introduced five unskippable ads for some YouTube users as part of a separate test – an unexpected development that, naturally, didn’t go down well with much of the YouTube community. 

A resolution paywall seems a more palatable approach from Google. While annoying, the change isn’t likely to provoke the same level of ire from non-paying YouTube users as excessive ads, given that many smartphones still max out at QHD resolution anyway. 

Of course, if it encourages those who do care about high-resolution viewing to invest in the platform’s Premium subscription package, it may also be more lucrative for Google. After all, YouTube Premium, which offers ad-free viewing, background playback and the ability to download videos for offline use, currently costs $11.99 / £11.99 / AU$14.99 per month.

Suffice to say, the subscription service hasn’t taken off in quite the way Google would’ve hoped since its launch in 2014. Only around 50 million users are currently signed up to YouTube Premium, while something close to 2 billion people actively use YouTube on a monthly basis. 

Might the addition of 4K video into Premium’s perk package bump up that number? Only time will tell. We’ll be keeping an eye on our own YouTube account to see whether this resolution paywall becomes permanent in the coming months.

Axel is a London-based staff writer at TechRadar, reporting on everything from the newest movies to latest Apple developments as part of the site’s daily news output. Having previously written for publications including Esquire and FourFourTwo, Axel is well-versed in the applications of technology beyond the desktop, and his coverage extends from general reporting and analysis to in-depth interviews and opinion. 

Axel studied for a degree in English Literature at the University of Warwick before joining TechRadar in 2020, where he then earned a gold standard NCTJ qualification as part of the company’s inaugural digital training scheme. 

Read More

Continue Reading

Tech

Europe sets deadline for USB-C charging for (almost) all laptops

Published

on

By

Europe sets deadline for USB-C charging for (almost) all laptops

USB-C als Ladestandard in der EU

Mundissima / Shutterstock


Author: Michael Crider
, Staff Writer

Michael is a former graphic designer who’s been building and tweaking desktop computers for longer than he cares to admit. His interests include folk music, football, science fiction, and salsa verde, in no particular order.

Read More

Continue Reading

Trending

Copyright © 2022 Xanatan