Add GitHub links for editing doc pages

Site Feedback
1

While reading Welcome to the Thousand Brains Project Documentation!, I wondered how to suggest changes for typos, etc. Guessing that the page’s source code might be on GitHub, I went looking around and (eventually) located the defining Markdown file.

This took me several minutes of hunting around and a bit more guessing. I suspect that many readers would have given up long before reaching this file, let alone making any edits. Consequently, their input would be lost.

So, I’d like to suggest an easy improvement. Please add a link to each documentation page, leading to its defining file. In addition, it might be useful to add a brief tutorial on using GitHub to edit doc pages.

Finally, though I’m not sure how to implement this, it might be useful to find a way to let users traverse the source files in the same order as the rendered files appear. The problem is that the source files are organized on GitHub by their directory paths and file names, so there is no convenient way to step to the file for the “next” doc page.

Although each doc page has a link to the next page, the source files do not. Both versions have sidebars, but the order on GitHub has little bearing on the order in the doc area. So, a prospective editor would need to jump back and forth between the doc area and GitHub in order to edit the pages in order. Tsk…

-r

2

Hi @Rich_Morin

Great notes, and thank you for all the PRs to the documentation! :sparkles:

We do have an item on our list for adding edit links to the documentation. This will require a change to the github_readem_sync tool. (tbp.monty/tools/github_readme_sync at main · thousandbrainsproject/tbp.monty · GitHub) If you’d like to have a go I probably won’t be getting to this for a few weeks.

There is a guide to editing documentation in the Contributing/Documentation guide here: https://thousandbrainsproject.readme.io/docs/documentation.
This guide also talks about the docs/hierarchy.md file, which you can use to navigate through the documentation easily in VS Code by CTRL/CMD by clicking on the links.

I created a new Github issue here to track: Add "Edit this page" links to pages in the documentation · Issue #107 · thousandbrainsproject/tbp.monty · GitHub

1 Like