What to do with old community documentation on GitHub

For a long time, there was a community-run project for unofficial Qubes documentation here:

Recently, all those community docs were migrated to the forum into this new section:

You can see the announcement for that migration here:

However, I still see people around the Internet mostly linking to the old GitHub guides, which are no longer being updated or maintained. I am wondering if we should take down those old guides or replace them with links to the new forum section. Any opinions?

“Why are people still using the old GitHub guides?” you might ask. I think it’s quite obvious once you replicate their experience. When you visit a page like this one, for example, there is zero indication that this document is deprecated, no longer maintained, and has migrated to the Qubes Forum. In order to learn that, you would have to back out to the root directory and read the README. I would not be surprised if the percentage of people who do that rounds to zero, especially for people who stumble upon these pages in search engine results.

There are at least two options:

  1. Simply remove/delete the content on GitHub as much as possible.
  2. Leave all the files in place, but update the contents of each file to a deprecation message with a link to the new forum section. The old content would still be available in the Git history.

The second option is less “destructive,” but it’s not clear that anything would actually be destroyed even with the first option. All the content is already here on the forum. Is there any reason to keep the old GitHub project around?

I guess one reason would be not to break any existing links that point to the GitHub files.

3 Likes

+1 for option 2 from me…I also stumbled upon the github guides first via a search engine…was quite surprised when finding the forum section and at first confused regarding its significance.

1 Like

I’d also favor option 2. which would also increase the discoverability of the Community Guides in the forum.

Idea: In order to account for the fact that multiple guides on the forum may have replaced a page on GitHub, the link could be a search scoped to the Community Guides category and terms relevant to the topic.

1 Like

If someone (you?) wants to volunteer to put in the legwork for that, we could have a specific link for each page. Otherwise, just having the same link on every page is probably still much better than nothing.

Yep, I think both options work. Indeed, I think that putting the same link to the Community Guides category is a good first step either way.

I took note of the issue and I am keen on helping with that once the what is settled.

I didn’t explicitly put my hand in my previous post because I’m not at my most responsive at the moment, so my legwork offer comes with a significant time caveat. (That’s to say, if anyone wants to jump in, please do!)

(An issue in GitHub may be worth opening for coordination once the details are settled, what do you think @adw?)

1 Like

Since this only involves cleaning up after an unofficial, community-run project, I don’t think it has any place in the Qubes issue tracker. It’s not actionable for any of the Qubes devs.

1 Like

Reasoning in relation to opening an issue makes sense @adw :+1:

For semantics, GitHub offers the option to archive a repository. That makes it explicitly “archived” and read-only.

1 Like

My opinion: the information should not be duplicated, especially when it is not synced by somebody. The outdated and unmaintained one should be hidden/removed.

But people do click and read old info for several reasons, including search engines respecting the old/original source a lot, people can have bookmarks that will stay up to forever.

So, the best solution is to modify github pages by removing all the information and only providing the link to the same page on the Forum. So that user will not need to search for the topic again. One sentence with a link to the same page on forum will be sufficient.

Search engines will eventually reevaluate modified github pages due to the lack of actual text and provide forum results, and while it is happening the users will inevitably read maintained and more up to date documentation and also being explicitly acknowledged about the transfer.

2 Likes

Good point. The more specific links can always come later, and since it’s a Git repo, any change can always be reverted later. With that in mind, I’ve done a quick first pass and opened these PRs:

If anyone else wants to do better versions, feel free to close these without merging. :slight_smile:

CC: @unman, @taradiddles, @deeplow, @Sven, @Plexus, @marmarek

4 Likes

I think it a mistake to remove the indexed links to the Forum. It would
be better to replace each one with a link to the new content.(This will
reduce friction in finding this material.)

We cant use the simplest method of redirecting from GitHub because the
new sites structure and naming is completely different from GitHub. So
the simplest method remaining is a meta refresh to the Forum.

On the Qubes side, we should point to the Forum Community Guides.
On the community GitHub there should be a refresh on each page with
redirect to the Forum, with link tag to new content.
This has an advantage that search engines should"get" the redirect and
maintain rankings to the new hosting.

3 Likes

Hm, I didn’t think I did. I thought I only removed links to the community GitHub repo.

Yes, I agree.

One of my PRs includes a link to the category, but it doesn’t include any more specific links than that (which would be better than what I submitted).

Hm, I’m not sure what a “refresh” is, but sounds probably better than what I submitted.

Ah, I see. Not sure if GitHub supports that, but if it’s doable, definitely sounds better.

Oh, I also realized (after submitting my PRs) that my removal of the redirect stubs in qubes-doc would break any links to qubes-doc that were getting redirected to GitHub, which is another undesirable thing.

Please feel free to do this all in better ways and close my PRs unmerged, @unman! :slight_smile:

I like it. Thanks for doing this and sorry for the reply delay!

I think @unman is referring to this change. Maybe the links could just be updated? @taradiddles may have all the links mapping?

But that’s not removing any links to the forum. It’s actually adding one.

But yes, I definitely agree that updating the links would be better; I just couldn’t find a good way to do it.

1 Like

Seems like some of the guides from qubes-community project weren’t migrated to the forum but their content was replaced with a link to the forum.
For example these guides:

Maybe it’s because the guides were inside one more nested directory.

Looks like the Ubuntu one wasn’t migrated.

Also I think all the links in the ‘External documentation’ section of the Qubes docs that point to that Github page, not sure if those should be updated as well?