Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

"Changelog" and "Edit on GitHub" links are for the repo, not the docs #51

Open
hraftery opened this issue Jan 31, 2023 · 0 comments
Open

Comments

@hraftery
Copy link

hraftery commented Jan 31, 2023

I noticed the "Changelog" and "Edit on GitHub" links in the top navigation bar take you to the repository from which the docs site was created. This is probably fine for a dedicated docs repo like fin-userManual-doc, where:

  1. the Changelog mostly consists of things related to the docs, and
  2. the user can (and should) be guided to making edits to the docs in the project README.

But imagine you're on this page https://os-docs.balena.io/faqs

Now those links take you to a changelog for meta-balena and to the meta-balena GitHub repo respectively, which would be bewildering for most.

Potentially it's useful to link to these things, but in those cases it probably makes sense to do so within the docs, not in the navigation bar where context can't be explained. So instead, maybe we:

  • only provide those links if the repo is dedicated, and in that case enforce what I believe should be standard anyway, and use the README as a description of the repo (eg. this is a docusaurus repo, source files are in here, output is there, references are here).
  • if the repo is not dedicated, remove the links and let the doc author create add details in the docs themselves if they wish. Losing a changelog link is probably no big deal for the user, and we probably want to be conscious on a per repo basis about providing a good experience for "edit on github". I know when I first joined balena, we had similar links on some of our resources and clicking them sent me into a rabbit hole of creating a useful edit and then realising I was way down the bottom of a long learning curve to figure out how to make it a useful PR.
  • make the links opt-in, so by default we eliminate this issue

Ideally, "Edit on GitHub" would take you to the edit page of the current file, but still that might be best to be optional for cases like meta-balena where making an edit is not for the faint-hearted.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant