The other day, I wanted to visit the latest POSIX specification of the `set` command, in order to confirm which safety flags are now supported. However, Google SEO continues to target old, outdated POSIX releases.
I read the red banner about the fact that newer documentation is available. But the hyperlink lands on a generic page, not the latest page for that specific command. The URL structure is unpredictable; URL hacking is unable to navigate from either old set to new set, or new make to new set. So I use the generic landing site. Which is not easy to integrate, because it uses 90's style frames. There's no single page option that includes everything, like the GNU docs. There's no ePUB or PDF download option. So I use the search form. I enter "set". The results are not prioritized by relevance like a modern fuzzyfind or elastic style text search. I skim the page looking for records that begin with "set". No matches. No pagination. Evidently the results are truncated to only the first 100 results. Which, again, are not ordered by relevance. Finally, a notice appears complaining that the query is too short. I give up on proof and rely on my memory of some ShellCheck open issues to explain to a coworker some context about how Snyk will eventually crash into pipefail in JSON mode, perhaps even in relatively common shell implementations such as Alpine ash. But I would have liked to provide him with a URL to the official POSIX spec. In summary, I think we have several opportunities to improve documentation navigation, downloads, and search.
