bitfocus
Leave references to moved documentation rather than 404s
Is this a feature relevant to companion itself, and not a specific module?
- [x] I believe this to be a feature for companion, and is not specific to a module
Is there an existing issue for this?
- [x] I have searched for similiar existing issues
Describe the feature
I maintain bookmarks to various documentation that I use regularly, such as the available functions' expressions & operators.
I just went to access the document at the saved URL: https://github.com/bitfocus/companion/blob/main/docs/4_secondary_admin_controls/expressions/functions.md and was greeted by a generic 404.
Only by proceeding to click back through the various parent directories until I found one that didn't return a 404 was I able to find that it had been moved to: https://github.com/bitfocus/companion/blob/main/docs/user-guide/4_secondary_admin_controls/expressions/functions.md
While I can understand that there are often circumstances that require or benefit from moving a page/directory to a new directory (I do it from time to time on my own website), it's not generally considered user friendly to 404 an established page.
I'm not sure if GitHub permits redirects, but that'd be the easiest way to handle it. Absent that, leaving the original URL with a note along the lines of:
This page has moved.
It can now be found at:
https://github.com/bitfocus/companion/blob/main/docs/user-guide/4_secondary_admin_controls/expressions/functions.md
Please update any bookmarks and references to reflect the new location & click the above link to be redirected.
would do a lot more for user experience than wholesale removing existing pages and leaving users who rely on them to go on a scavenger hunt to see if the page still exists and where.
I'd be happy to do it myself, but I only know about those 2 moved pages that I know about. I'm not sure what all was originally somewhere else & moved and what was created new at the new location.
I also think it's something that should be considered for being made SOP moving forward when established pages are moved.
I do understand that, absent a proper redirect, there'd be a level of bloat from pages that exist only to point users to other pages, but that's, in my opinion, one of the risks of making a choice to move pages & directories that may have external references/links/bookmarks.
Usecases
No response
As far as I'm aware, github doesnt support redirects here, as those pages are linked to source files. Every page of documentation has moved, with some merged, split or just generally rearranged as part of rebuilding the documentation in a new system which allows for nicer rendering inside companion as well as at https://companion.free/user-guide/
While I agree that it would be nice to not break these links, handling this is non-trivial. While we could make ~50 files to point viewers to the new ones, as they would have to perfectly match the old locations within the repository, they will get in the way when updating the documentation, and add confusion to that process (and that assuming it doesnt upset the documentation build tools)
If it wouldn't break anything & if there's a record somewhere of what got moved where (especially in cases of page merge/splits), I'd be happy to personally and manually create a page at every location with a link to the new location.
If it wouldn't break anything & if there's a record somewhere of what got moved where (especially in cases of page merge/splits), I'd be happy to personally and manually create a page at every location with a link to the new location.
That's not a particularly sustainable solution, nor is it particularly good user experience to have dozens of files to be maintained that do nothing other than to point users to another file. Plus it would further complicate things if we were to move the docs elsewhere, such as their own dedicated module, or some other such place.
I think ideally people shouldn't be bookmarking specific files in Github as there is always the potential for them to move in the future, be split into multiple other files, or simply deleted. I also don't have any data on this but I haven't seen any other user on any other repo have issues such as this, so I feel that the impact of users bookmarking a file that no longer exists is not particularly a problem, certainly not worth over-engineering a solution for that would result in cluttering up the repo.
nor is it particularly good user experience to have dozens of files to be maintained that do nothing other than to point users to another file
They don't need to be maintained, as they'd only need to updated if the original file moved again.
Ideally, moving a file shouldn't be done with any regularity. As I said, there are certainly situations that require it, but it should be considered a serious change of nearly last resort.
I'd also question the discrepancy between the supposed poor UX of having multiple files in the document tree and the suggestion that users not maintain standing references to files in the document tree.
I'd suggest that if the documentation area of the repo is for users to access the documentation, users would have a rightful expectation that the documentation would remain where they know it to be.
If users are meant to access the documentation outside of the repo, and, thus, have no expectations as to where in the repo the files would be, they'd in no way be hampered by the existence of additional files in a repo they aren't meant to be accessing.
I think ideally people shouldn't be bookmarking specific files in Github as there is always the potential for them to move in the future, be split into multiple other files, or simply deleted.
Hence the feature request regarding a change to SOP as it relates to relocation of files.
I see it as no different than any other breaking change & believe it should be taken just as seriously.
An expectation that a relied upon functionality of the underlying program not be deleted should be just as reasonable as an expectation that a relied upon piece of documentation not be deleted.
I also don't have any data on this but I haven't seen any other user on any other repo have issues such as this
I believe I've made this point before, but the idea that every user who takes issue with something will make that known is a fallacy.
You know how many people you've seen report an issue--you don't know how many you've seen who had an issue with it and kept it to themselves.
Let's not conflate the two.
Heck, I've even seen cases where the ReadMe on a repo would link to non-existent documentation that had either moved or been outright deleted.
Did I take issue with it, just as I do here? Yes.
Did I voice it? No, because, unlike here, I wasn't passionate enough to offer to take on the work of fixing it & simply pointing out that the links on the main page didn't work (something they presumably already knew) wouldn't have been a constructive use of my time.
At the end of the day, it's an open source piece of software with an issue that I identified and am willing to invest my time in fixing.
Do I know how many people it's impacting? No. But I also don't think highly enough of myself to think I must be unique among all the users of the program, so I'm guessing it's more than 1.
So I'm leaving it here as a feature request for a discussion of what steps might be able to be taken, along with a willingness to do the work personally to take those steps.
I feel that the impact of users bookmarking a file that no longer exists is not particularly a problem
But this is where we disagree.
I think any issue that negatively impacts a user is a problem.
The questions are simply about the appropriate scope and nature of the fix, and whether the fix would cause more problems than it'd solve.
They don't need to be maintained, as they'd only need to updated if the original file moved again.
Another word for that is needing maintenance ;)
I'd suggest that if the documentation area of the repo is for users to access the documentation, users would have a rightful expectation that the documentation would remain where they know it to be.
If users are meant to access the documentation outside of the repo, and, thus, have no expectations as to where in the repo the files would be, they'd in no way be hampered by the existence of additional files in a repo they aren't meant to be accessing.
I think the disconnect here is that it was never intended for users to view the documentation within this repository directly.
The files you were viewing are the source code used for building the getting started guide within companion and the documentation on the bitfocus website.
Neither of those are publicly accessible without logging in, so I can understand why you have found and started using these files.
But this leaves us with the problem of that to support the new documentation renderer, we need to move the files and restructure them a bit to get it to render nicely. Maybe some don't need to move, but that would leave a mess for any companion core developer to navigate around whenever working on companion.
(And tbh I will forget about this discussion in 6 months and move them again)
Going forward, viewing at https://companion.free/user-guide/ will be better, and hopefully the page links should be pretty stable as they are based on headings rather than exact paths on disk. (but things will likely still move at times).
Problem being that this is an initial port of the docs and they may undergo a bit of a rewrite when updating them for the 4.2 release.
My intention is that once 4.2 is released to enable the versioning feature of that docs site, meaning docs for older versions would be viewable. It isnt trivial to import older versions into this though, so that likely wont happen for 4.1 or older.
The question remains on what to do about this. Is this a common problem users will be facing with us having moved these docs? Because I'm not sure who to force some pain on; its either the devs having to work around these 'redirect' files or the users having their bookmarks broken and needing to learn new urls.
Keep in mind that Github is not the only source of user feedback. There are Facebook groups, multiple Discord and Slack servers, working actual events and various production studios, and having people reach out to us directly, so while you're absolutely right that many wont make a Github issue for something, little issues in peoples workflow or things that are a bad user experience do often come to light even if it's quite minor, and as I previously mentioned I've not heard of anyone else have issue with this but you.
Secondly, Github is a developer first platform. The primary source of user manual is the Getting Started/User Guide that's built in to Companion itself, and shown in the Web UI, as this will always provide a consistent source of information relating to that specific version of Companion, where as GitHub will always have docs for whatever is the latest beta version which may not be correct as to what a user is running.
I think a more ideal solution and less half-assed as making lots of files just to tell a person to go to another file, would be to continue what we're doing with the Getting Started/User Guide within Companion itself, but also consider something along the lines of building an static page from the docs here on Github and having it sent to something like S3 which can be automated, and provide a static User Guide site that can be accessed outside of Companion and the original source material can be in any files or structure as it wants as long as it builds and output the same way then it will be entirely hidden to end users as they wont need to know the file structure on Github. This could even be done in a way to allow versioning of the help guide (much in the same way vMix provide their help guide through a /help28/ path for docs on vMix 28, /help29/ path for docs on vMix 29, etc... This would also be a better user experience for end users for docs than Github.