[RFE] Hooks for attaching OS and system-specific documentation

[sgallagher]

I'd very much like for Fedora Server to be able to ship a small configuration file that would specify a web URL for documentation about how to use the system (starting with a guide of Cockpit and then also including more complex configuration such as command-line tools and configuration management systems).

My view of how this would work would be a documentation or help tab that would read a config file (or, ideally, /usr/lib/cockpit/docs.d and /etc/cockpit/docs.d directory of config files) to provide links to documentation.

I'd like to see these as drop directories on the disk so that we can allow individual projects to carry a link to their documentation here if they wish. I'd suggest we'd want these to be searchable in some way; I'm not going to attempt to dictate a full specification, but I'd like to see something where the configuration can select a primary top-level description (e.g. "System Management", "BASH Console Basics", etc.) as well as an arbitrary number of tags that could be used for searching.

[sgallagher]

In the specific case of Fedora Server, I'd like an appropriate place to drop a link to https://docs.fedoraproject.org/en-US/fedora/f28/system-administrators-guide/ which provides a lot of really useful beginner information for Fedora.

[martinpitt]

Our front page already has support for showing (and clicking away) /etc/motd. This is rather close, a well-known concept, and easy to customize for administrators as well. Cockpit doesn't show /etc/motd.d/* though, and I think it should. We just need to filter out our own /etc/motd.d/cockpit 😄

But maybe this is too intrusive, as it would appear every time when logging into Cockpit. Another strawman is to add a "Help..." entry in the top right menu, with a distro-configurable URL (./configure --help-url="..." ?)

[mvollmer]

But maybe this is too intrusive, as it would appear every time when logging into Cockpit.

Cockpit is supposed to remember the text that has been dismissed, and only show the motd again when it has changed. I think this might be broken, actually.

[sgallagher]

I think you misunderstand my intent here. While my specific desire for Fedora Server's docs would fit as a Help menu item, I actually do want this to be more comprehensive such that we could allow any other packages (or Server Apps) to drop a configuration in place to link to their documentation.

I'm envisioning something like the Yelp tool on GNOME, but somewhat more curated. For example, we don't need to have all manpages referenced, but I might add a link out to ManKier, which isn't Fedora-exclusive, but very useful.

That said, if you feel that linking to a single doc site makes more sense for Cockpit, I can work with that. It just limits us to only being able to present Fedora's docs and not to allow third parties to add their own.

[martinpitt]

There's two different use cases here. If there is some general OS/Cockpit docs (like https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html-single/getting_started_with_cockpit/index for RHEL), that should be somewhere in the top-level navigation (user menu, or a link to the left of it in the top bar). That's the bit with the ./configure --help-url.

But if some specific cockpit page (e. g. "Networking" or a server app like "FreeIPA installer") has some documentation, then it IMHO makes much more sense to put that link onto that page. Putting it somewhere else would be too disconnected from the page. This can happen for both installed extensions (which have full control over their page contents) as well as un-installed ones that get offered on the "Applications" page (again, these have full control over the AppStream data, which can include doc links). So for these I don't think we need to invent anything new.

[sgallagher]

OK, I think I can agree with almost all of that. I do think we still want to have a general OS doc that is specified at runtime rather than compile-time though, and here's why:

The documentation for Fedora Server and the documentation for Fedora CoreOS are probably not going to be the same. Yes, we could have a common landing page that users then clicked through, but I think it would be a much better user experience if the link we provided goes straight to the main documentation.

Considering it further, I think the proper approach here would be to propose a new option for /etc/os-release, similar to what we did with VARIANT/VARIANT_ID for the Fedora Editions. Right now, the os-release specification includes HOME_URL=, SUPPORT_URL=, BUG_REPORT_URL=, and PRIVACY_POLICY_URL=. So adding DOC_URL= would seem to be in keeping with that intent.

If we add DOC_URL to the os-release spec, could we have Cockpit include the top-level doc link if it is present (and quietly suppress it if unspecified)?

If that makes sense to you, I'm going to propose adding this field to the os-release upstream.

[larskarlitski]

Fedora 29 has DOCUMENTATION_URL now and it links to the System Administrator's Guide. Where would we want to show a link to that? In the menu on the top right?

[sgallagher]

Under the user menu in approximately the same place as "About Cockpit" perhaps?

[larskarlitski]

Under the user menu in approximately the same place as "About Cockpit" perhaps?

Good idea. @andreasn what do you think?

[andreasn]

Under the user menu in approximately the same place as "About Cockpit" perhaps?

Yeah, I think this is where I would look for it. I'm all right with that.
Does RHEL, Debian etc. have the DOCUMENTATION_URL thing as well, or is it fedora exclusive for now? Might want to hide it on those systems if it's not there.

[sgallagher]

It is not guaranteed to be present, but if it is we should really show it.

[andreasn]

I also realized it's a systemd thing now. :)
So let's call the entry Documentation and hide it if it's not set in the systems OS release file.

[sgallagher]

Should we perhaps call it "System Documentation" instead of just "Documentation" to make it clear that it's not documentation for Cockpit itself?

[andreasn]

yeah, that works for me

[andreasn]

[jgiardino]

Miscellaneous comments:

The menu could better accommodate links to documentation for other applications. Will it be possible to add these documentation links to the masthead (e.g. a link to Image Builder documentation)?

For any links that open in a separate window, we need to provide indication to the user. In PF, I think the pattern for this is an icon. I can try to find examples of this.

For cases where we have help tooltips/popovers, we should have a consistent pattern for differentiating between links that will navigate to documentation versus these embedded help controls.

[larskarlitski]

The menu could better accommodate links to documentation for other applications. Will it be possible to add these documentation links to the masthead (e.g. a link to Image Builder documentation)?

It's not yet, but I could imagine a documentation_url field in the manifest that the shell could read and put into the masthead.

[andreasn]

While this works great for Fedora, I'm a bit unsure about what documentation that is best to link to in RHEL.

In the case of RHEL 8, you have the general system documentation. This includes how to install it, CLI usage, web console, etc, mixed together. Then there is the documentation specifically for the web console.
The documentation that is specifically for the web console is the one that I think is most relevant for people using the web console, but I would hesitate to set that as DOCUMENTATION_URL= for RHEL as a whole.

I think RHEL is the only distro that has specific web console documentation though, so maybe it's easiest to just point to the DOCUMENTATION_URL= and then let people find their way from there.
The specific pain points can be solved with inline documentation.

[andreasn]

@marusak is working on implementing this in #13376