Proposal: trim down documentation repo

[ghost]

The documentation repo is home to the source of the documentation section of the official Pi website, raspberrypi.org. Originally, the documentation section was the only official source of long-form information about Raspberry Pi: the other main sections of the website were the blog, and the forums. Over time, much more long-form content was added: projects.raspberrypi.org, MagPi content, and teaching resources to name a few. There was also, quite early on, a split to create a wholely owned subsiduary company - Raspberry Pi (Trading) Ltd, which was given custody of the documentation repo.

Raspberry Pi (Trading) Ltd is responsible for the trading aspects of what Raspberry Pi does: broadly, this means products. Trading does this to support the charitable mission of the Raspberry PI Foundation. So far, so good. However, since the documentation section of the website, and this documentation repo, was created before the creation of Trading, it contains documentation which should be managed by the Foundation. There is also duplication between the other parts of the website and the documentation section.

My proposal is to refocus the documentation repo, and the documentation section of the website, on technical product information, and either delete other content it currently contains, or move it so that it is under the control of the Foundation.

Pros:

• Reduced maintenance requirement (of docs repo)
• Reduce duplication of content and effort
• Make things less complicated for users

Cons:

• Potential loss of useful documentation
• Dead links will be created when cull occurs

My proposal for the various sections of the documentation repo is as follows: (sections being defined by the images present at raspberrypi.org/documentation):

• Setup / quickstart - remove. The main download page at https://www.raspberrypi.org/software/ is really good, and we've got a much better install tool now - Raspberry Pi Imager. The setup / quickstart part of the docs doesn't actually say very much, and I'm not sure how many people actually read it anyway. The "help" box on https://www.raspberrypi.org/software/ should perhaps be enhanced to add a link to the forums.

• Installation - remove. Again, there's not much here, and the installation process is much better than it was. Note that for this section, and the "setup / quickstart" section, there's also dedicated equivalent sections elsewhere on the website: they even have prominent links right on the help page (https://www.raspberrypi.org/help/): "Get started with Raspberry Pi" and "Setting up your Pi". Also, there should be a link to https://www.raspberrypi.org/help/ in the help box on https://www.raspberrypi.org/software/.

• Usage guide - move to Foundation. Most of these apps are not Pi-specific, and there are tutorials elsewhere on the website for most of those. For those that don't, I would posit that this is a pretty good indication they're not necessary. Some are out of date - e.g. the sections on Kodi, audio, and video playback. (Also the fact that these are out of date and nobody seems to have pointed this out until now would tend to suggest that hardly anyone is looking at them anyway).

• Configuration - keep

• Remote access - keep

• Linux - keep some of it, but remove generic Linux stuff that has tutorials elsewhere, e.g. in MagPi online content (not PDFs) - point to those instead.

• Raspberry Pi OS - remove installation and upgrading info, keep docs for Pi-specific apps.

• Hardware - keep, but reorganise. The products section of the website (https://www.raspberrypi.org/products/) has really good basic technical info about each Pi including specs.

The sections to keep should be reorganised into new sections that are better focussed: I had a quick stab at it, but didn't come up with much. I would like to volunteer to lead the proposed reorg.

[aallan]

As you may know already I've been brought on to head up technical documentation at Trading. However pretty much all of my time since I started a year ago has been devoted to documentation around Raspberry Pi Pico and RP2040.

However now Pico is launched into the world I will, soon(ish) be looking towards the mainline documentation.

I have provisional plans around how things are going to go, and there are some big changes coming. A pruning of the documentation back to something a bit more streamlined and focused is going to be part of that. After all the existing documentation grew organically.

Thanks for the proposal. I'll certainly consider this alongside my existing and still provisional plans. It really helps to get feedback like this!

More on this soon once the feedback and traffic from the launch of Pico has subsided to a dull roar.

[lurch]

After all the existing documentation grew organically.

Indeed! When this repo was first created there was a LOT less 3rd-party content around Raspberry Pis than there is now, and many people had no idea what this "Linux" thing was (or what you could do with it), which is why (in hindsight) much of the documentation now seems overly-broad.

EDIT: Haha, my very first commit to this repo: a08a803 - nearly 7 years ago!

[ghost]

When this repo was first created there was a LOT less 3rd-party content around Raspberry Pis than there is now, and many people had no idea what this "Linux" thing was (or what you could do with it), which is why (in hindsight) much of the documentation now seems overly-broad.

My feeling is that the parts of this repo you refer to were required at the time, but have been superceded by better content elsewhere on the website.

There's a broader issue about how all of the various bits of the website fit together in terms of both overall navigation, and the interconnections between the various sections, e.g. between projects.raspberrypi.org and the MagPi online content, and the documentation section. Perhaps it's time for a knowledgebase type section, or a section dedicated to task-focussed tutorials (which is not really what projects is about - that's more about projects designed to assist learners). Also, the forums are full of stickies with lots of good tips in them, which also contain plenty of out of date content.

One thing I have been meaning to have a look at for the documentation section is a style refresh, as the rest of the website (except forum) has had the style updated but the docs repo hasn't. There's at least one bug in the old style that I know of, and a couple of other things that don't quite look right. Plus I think the new style on the rest of the website, particularly the white background, is an improvement over the old look that the docs part is still using.

[aallan]

See #1911