It's time to retire Yelp

Yelp is in a pretty sad state right now:

  • There is a dangerous vulnerability that’s gone 90+ days without any attention (until last week)
  • The last release was 2 years ago (42.2)
  • Still hasn’t migrated to Gtk4 and Human Interface Guidelines

All this raises several questions about Yelp’s future:

  1. Do we even need it? Could existing Gtk4 apps like Biblioteca or Epiphany be forked/modified/adapted to open help pages?
  2. Does Yelp actually provide any real benefits to end users? To get help, most “normal” users will just go to Google/Reddit/chatGPT, and most “power” users will just read the man pages in a terminal. I’m inclined to say “no” considering that Yelp’s development has lagged so far behind other core apps
  3. If a standalone help reader is still needed, should Yelp be forked so that we can get moving on the Gtk4 port? (i.e. what Papers did to Evince)

Retire and replace with what?

Yelp loads the native help pages, written using Mallard, and turns them into HTML.

You’re trying to extrapolate your own experience into a generic “end user”; this never ends well, especially if you’re not familiar with the whole tech stack you’re consuming.

Who’s going to fork it?

Biblioteca is something entirely different (API docs for developers).

This merge request adds support for opening help documents in a web browser, but the user experience will not be nearly as nice as normal Yelp.

Endless provided us with some stats indicating that extremely few users ever open Yelp. However, I do not have a reference for this, and I don’t remember what the actual numbers were. Maybe @wjt could help with this.

Another problem is the GNOME documentation team is no longer active, and new core applications do not have any user help at all.

I think it’s time to consider the future of user help in GNOME. I don’t know what the solution should be and I’m not sure retiring Yelp is the right path forward, but certainly it doesn’t really make sense to have local user help anymore if nobody is maintaining the help documents. Rebuilding an active docs team would be much harder than just maintaining Yelp.

There is a GTK 4 port here.

Thanks everyone for reading this! I do think there should be an honest, constructive discussion about the best way forward for user help in GNOME, since most end users are clearly not using Yelp, developers are not keeping up with issues, and the information is outdated

@ebassi I was thinking that since yelp-tools can generate HTML on the fly and pipe it into Epiphany (or some other Gtk4 viewer like Biblioteca), having Yelp as a standalone app doesn’t make much sense any more. That means it would be “retired and replaced” with nothing: yelp-tools and Epiphany would take over its main functions. That solves the “outdated, vulnerable Gtk3 app” problem

The other (more serious) problem is the “how do users get up-to-date help docs?” problem. I wasn’t aware that the documentation team is no longer active. But again, do users really need offline help pages? @mcatanzaro found data that users are not opening Yelp. Could new help information just come bundled in GNOME Tour (with screenshots!), or be documented on a central GNOME website? Could we put AI to work writing basic documentation?

In any event, these deserve some thoughtful discussion

In March, 713 Endless OS users launched Yelp, compared to 19,000 Chrome users and 13,600 Nautilus users (the top two most-used apps).

If we assume that 10 seconds is the minimum time to find an answer to a question in Yelp and exclude all users who had Yelp open for a total of less than 10 seconds, the number falls to 452.

I remember the numbers being a bit higher in the past but am not able to look back over historical data today. Potentially relevant facts that mean you should not draw too many conclusions from these numbers:

  1. We patch Yelp to install a desktop search provider. You might hope that this inflates the number a little. We do not have data on whether people use these search results.

  1. For apps installed via Flatpak, which on Endless OS includes most of the core apps, the Yelp that gets launched when you hit F1 is the copy bundled in the Flatpak runtime, and is not attributed to Yelp in the data I’m quoting above – it’s attributed to the app in question. So hitting F1 in Loupe does not count as launching Yelp. So this number is an underestimate. It only counts help for the desktop itself (launchable from the Help app grid icon), Nautilus, Evince, Evolution, Simple Scan, Clocks, Malcontent.

  2. In the past we would place the Help (yelp) icon on the first page of the app grid (i.e. the desktop on Endless OS) and there was an item for it in the system menu. I remember the numbers being higher in that case.

4 Likes

This might work for the desktop help, but in no way, shape, or form works for application help. Right now, we’re putting Yelp into the Platform run time to allow it to see the application’s help directory inside the sandbox; there’s no way we’re going to ship a fully functional web browser into the run time. It’s just nonsense.

“Or some other Gtk4 viewer”: so you’ve committed yourself to write a Yelp replacement that uses the same tech stack—unless you also committed yourself to rewrite the documentation of every application; and all of it to end up with the same issue as Yelp: in order to display HTML you still need to have a web rendering engine running.

Please, don’t come to the GNOME project to tell other people what to do. You just volunteered to:

  • maintain Yelp or
  • rewrite Yelp
  • maintain the desktop and application documentation or
  • rewrite the desktop and application documentation

I think it might work if you install the patched yelp-tools in the runtime.

1 Like

Sorry, that’s my fault for not communicating very clearly. I actually am willing to help out on Yelp over my upcoming semester break - I’m just questioning whether it’s the smartest / best thing to do. As you can probably tell from the title, I think that even if Yelp was ported to Gtk4 today (unlikely), it wouldn’t solve Yelp’s main problems of low user interaction and outdated docs. I’m therefore in favor of the “burn it to the ground and start from scratch in Rust” approach, but I figured that was too edgy of a title

However, I fully admit that this is my (limited, flawed) perspective as an end-user. If the GNOME core team is invested in maintaining and improving Yelp, I’m happy to step up and contribute code. I just don’t want to spend my whole summer contributing code to a project if that project is functionally abandoned and my pull requests will just sit there with no review or discussion for months (like what happened with the most recent CVE)

So I’m trying to figure out the best way for me to help maintain/contribute to Yelp:

  1. Ask nicely to become a maintainer (when nobody knows or trusts me) so I can fast-track the Gtk4 branch
  2. Fork Yelp and create a new Gtk4 app that does the same thing (potentially alienating the current Yelp devs and burning lots of bridges)
  3. Starting from scratch with something written in Rust

My summer break is coming up, and I’m not sure which track (1,2,3) is wisest to pursue. That’s what I’m trying to get us to talk about here :slight_smile:

6 Likes

The main issue here is that there isn’t a documentation team. Unless that changes, the future of Yelp (or a rewrite of it) is uncertain.

2 Likes

to (2.): an important things about user-docs is that they are internationalized, while on google you’re not going to find much if you try to search in a less popular language (and people say google and other web search engines are only getting worse)