5

Since this past weekend, I've found that virtually all links to the "official" documentation are broken. Visiting the site just now shows why this is. The front page looks similar, except for the addition of a long-overdue "search" feature. But AFAICT, all of the content now is massively scrambled into a new hodge-podge organization.

Hopefully, this is just an interim step for them, but as it stands today, it would seem that almost each and every link on RPi SE that pointed to "official documentation" is broken - as in "404 Broken".

Does anyone know what's going on? Is there a plan - or is this Brownian Motion?

3
  • 1
    Ahh... "improvements" :-(
    – Ghanima Mod
    Aug 10, 2021 at 7:36
  • There seems to be some progress here: i.e. raspberrypi.org/documentation/hardware/raspberrypi/schematics (that I used to use often) now redirects to raspberrypi.org/documentation/computers/raspberry-pi.html w/o 404
    – Ghanima Mod
    Aug 19, 2021 at 7:52
  • @Ghanima: Define "progress" :) Getting rid of the "404s" is a step forward, but a small step. It was done after-the-fact - apparently without an understanding or consideration of the implications. This new "system" leaves us (SE) with many thousands of broken links to the "official" documentation. They may not be "404s", but they don't take the reader to the cited documentation. Instead of taking the reader to a reasonably specific passage in the docs, they now lead to a broad, general topic - which may or may not be the correct topic. I fail to see the "improvements" in this.
    – Seamus
    Aug 19, 2021 at 19:53

2 Answers 2

Reset to default
4

I am generally not a fan of the Foundation's software, and up until this point found the website nearly unbearable -- it was the equivalent of a small room piled knee deep with unbound paper that was thrown in blindfolded (or at least, it was toward that end of the "usability" spectrum").

At a glance right now though -- and I dunno if stuff was fixed there since the Q was written 16 hours ago -- I am impressed, the doc portable is a considerable improvement.

The thing I found confusing initially is that there are three big general categories on the front, "computers", "accessories", and "microcontrollers" over what looks like corresponding columns of subcategory icon (they are inline visually), by which I mean it initially looks like column 1 is about "computers", 2 about "accessories", etc.

But that is not the case, all the icons are part of whichever of the three is currently selected. This is kind of a functionality for regular users vs. simplicity for new ones issue that could probably be resolved easily but isn't a huge deal. Having only one minor criticism counts as pretty good for me.

Then there's the issue of the broken links, which also could have been resolved easily enough -- if they didn't want to stick to the structure, they still could have ripped some (likely, most) of the important paths into a redirect system. The links then still sort of remain "broken" but there would at least then be an easy way to find the same/similar material.

It seems there is now no way to link to specific information, only to a few broad headings.

It's at least as specific as it was, eg:

This could almost shut us down, lol.

8
  • It's a lot of broken links... is there a tool that could tally all of that? Translated into man-hours, it seems overwhelming - particularly since there's no "mapping" of old-to-new. I'll confess: I am struggling to see it in the positive light you seem to have found. The comments here suggest that this may not have been the most coordinated or well-planned move of all times.
    – Seamus
    Aug 10, 2021 at 21:01
  • "is there a tool that could tally all of that" -> 'Link' can refer to the URL in an anchor to another page, or the local links embedded in the page (these are referenced with #foo at the end, #foo being a specific point in a page). So, what I meant was, when they were putting that together a fair bit of manual work was required (even if it scripting something to automate most of it). When they were doing that, it would have been easy to pair existing page/#foo links with new ones, then given that to the web server as a set of redirects.
    – goldilocks Mod
    Aug 10, 2021 at 22:08
  • ...For you or I or whoever external to the process, though, reversing that would be incredibly tedious and I cannot imagine there is much in the way of tools to help with that although perhaps I am not being imaginative enough (certainly something that scanned and matched chunks of text would be helpful). Also, the best you could do with such a list then would be to post it somewhere, which is way less useful than having the foundation server do redirects.
    – goldilocks Mod
    Aug 10, 2021 at 22:08
  • Could the urls be mass replaced with archive.org links until they're manually replaced?
    – GammaGames
    Aug 10, 2021 at 23:20
  • 2
    The person who perpetrated this mess has posted (defending his actions - reminds me of a politician) saying it would be a big task to redirect the links, which is true. The alternative is for the hundreds who maintain tutorials to do so which is a big task * hundreds. There have been a couple of changes since the original fiasco so I will wait and see. This is certainly not the way I would have rolled out a change; what about the alternative of testing on a small sample?
    – Milliways
    Aug 11, 2021 at 0:17
  • At least most of the links which gave 404 now go SOMEWHERE even if they fail to hit the target.
    – Milliways
    Aug 11, 2021 at 0:20
  • @GammaGames: It seems I recall something that automated that... url-rewriter, or ...??? But for that to be effective, I think it might need to be in the RPi S.E. website. I'll guess that's maybe even less likely than The Trading Company doing something responsible.
    – Seamus
    Aug 11, 2021 at 0:24
  • @Milliways: The phrase "brain-dead" comes to mind. And as I read the comments on the documentation GitHub site, I get the feeling this was very much uncoordinated incompetence. Wouldn't the responsible thing to do be get the redirects and a specialized 404 page set up before pulling the plug? Yeah - I'm pretty pissed at the cavalier attitude. But you & @goldilocks are correct: let's wait and see.
    – Seamus
    Aug 11, 2021 at 0:38
4

There was an Announcement https://www.raspberrypi.org/forums/viewtopic.php?f=63&t=313412

Not only have the links been broken, in the process the documentation has been flattened e.g. you CAN now find config.txt (if you are determined) but you have to read pages to find anything.

I used to have a link to Conditional Filters, now you have to

  1. know it is there
  2. go to line 3041

It seems there is now no way to link to specific information, only to a few broad headings.

Based on the response to the outcry about the other recent changes to the site (the top half of your screen is useless oversized repetitive graphic links) don't expect any improvement.

I updated a couple of the links in my networking tutorial.

They now kind of work, but are very slow.

They download a ~32,000 line html file!

The link goldilocks posted in comments is 643k.

But look on the bright side; the job of the documentation writers is now easier, pity about the users.

2

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .