Skip to content

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

@hraftery

Description

@hraftery

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions