You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
the Changelog mostly consists of things related to the docs, and
the user can (and should) be guided to making edits to the docs in the project README.
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.
The text was updated successfully, but these errors were encountered:
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:
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 themeta-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:
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.The text was updated successfully, but these errors were encountered: