Bring on the documentation

I joined Raspberry Pi eighteen months ago and spent my first year here keeping secrets and writing about Raspberry Silicon, and the chip that would eventually be known as RP2040. This is all (largely) completed work: Raspberry Pi Pico made its way out into the world back in January, and our own Raspberry Silicon followed last month.

The question is then, what have I done for you lately?

The Documentation

Until today our documentation for the “big” boards — as opposed to Raspberry Pi Pico — lived in a Github repository and was written in Github-flavoured Markdown. From there our documentation site was built from the Markdown source, which was pulled periodically from the repository, run through a script written many years ago which turned it into HTML, and then deployed onto our website.

This all worked really rather well in the early days of Raspberry Pi.

The old-style documentation

The documentation repository itself has been left to grow organically. When I arrived here, it needed to be restructured, and a great deal of non-Raspberry Pi specific documentation needed to be removed, while other areas were underserved and needed to be expanded. The documentation was created when there was a lot less third-party content around to support the Raspberry Pi, so a fair bit of it really isn’t that relevant anymore, and is better dealt with elsewhere on the web. And the structure was a spider’s web that, in places, made very little sense.

Frankly, it was all in a bit of a mess.

Enter the same team of folks that built the excellent PDF-based documentation for Raspberry Pi Pico and RP2040. The PDF documentation was built off an Asciidoc-based toolchain, and we knew from the outset that we’d want to migrate the Markdown-based documentation to Asciidoc. It’d offer us more powerful tools going forwards, and a lot more flexibility.

After working through the backlog of community pull requests, we took a snapshot of the current Markdown-based repository and built out a toolchain. A lot of which we intended to, and did, throw away after converting the Markdown to Asciidoc as our “source of truth.” This didn’t happen without a bit of a wrench; nobody throws working code away lightly. But it did mean we’d reached the point of no return.

The next generation of documentation

The result of our new documentation project launches today.

The new-look documentation

The new documentation site is built and deployed directly from the documentation repository using Github Actions when someone pushes to the master branch. However we’ll mostly be working on the develop branch in the repository, which is the default branch you’ll now get when you take a fresh checkout, and also the branch you should target for your pull requests.

We’ve always taken pull requests against the Markdown-based source behind our documentation site. Over the years as the documentation set has grown there have been hundreds of community contributors, who have made over 1,200 individual pull requests, ranging from fixing small typos, to contributing whole new sections.

With the introduction of the new site, we’re going to continue to take pull requests against the new Asciidoc-based documentation. However, we’re going to be a bit more targeted around what we’ll to accept into the documentation, and will be looking to keep the repository focussed on Raspberry Pi-specific things, rather than having generic Linux tutorial content.

The documentation itself will remain under a Creative Commons Attribution-Sharealike (CC BY-SA 4.0) license.

Product Information Portal

Supporting our customers in the best way we can when they build products around Raspberry Pi computers is important to us. A big part of this is being able to get customers access to the right documents easily. So alongside the new-look documentation, we have revamped how our customers (that’s you) get access to the documents you need for commercial applications of Raspberry Pi.

The Product Information Portal, or PIP as we’ve come to refer to it here at Pi Towers, is where documents such as regulatory paperwork, product change notices, and white papers will be stored and accessed from now on.

The new Product Information Portal (PIP)

PIP has three tiers of document type: those which are publicly available; restricted documents that require a customer to sign up for a free account; and confidential documents which require a customer’s company to enter into a confidentiality agreement with Raspberry Pi.

PIP will also be a way for customers to get updates on products, allowing customers with a user account to subscribe to products, and receive email updates should there be a product change, regulatory update, or white paper release.

The portal can be found at pip.raspberrypi.org and will be constantly updated as new documents become available.

Where next?

I’m hoping that everyone that has contributed to the documentation over the years will see the new site as a big step towards making our documentation more accessible – and, as ever, we accept pull requests. However, if you’re already a contributor, the easiest thing to do is to take a fresh checkout of the repository, because things have changed a lot today.

Big changes to the look-and-feel of the documentation site

This isn’t the end. Instead, it’s the beginning of a journey to try and pull together our documentation into something that feels a bit more cohesive. While the documentation set now looks, and feels, a lot better and is (I think) a lot easier to navigate if you don’t know it well, there is still a lot of pruning and re-writing ahead of me. But we’ve reached the stage where I’m happy, and want to, work on that in public so the community can see how things are changing and can help out.

32 comments
Jump to the comment form

Avatar

It’s great to see you putting such a great effort into improving the documentation – and such a shame that you completely missed the opportunity to ensure that the documentation site and published content meets WCAG-2.1 accessibility standards … as with much in the maker and linux communities, accessibility is woefully neglected!

Reply to Mike

Alasdair Allan

The toolchain and documentation are available in Github. We’d be happy to take pull requests to help support increased accessibility and access.

Reply to Alasdair Allan

Avatar

Much of accessibility begins and ends with layout and the “way you do things”. This should be something considered right at the start, as you develop, not something that is bolted on by non-staff afterwards.

Reply to Michael Horne

Avatar

It certainly does.
Quite possibly RPF or RPT have someone there that knows, else you wouldn’t have this accessibility guideline page linked and posted for all to see.
https://www.raspberrypi.org/accessibility/
It is there at the bottom of all your web pages if needed.
You’re aiming for AAA and that should be in the design brief from the start.
What does it rank at at the moment.

Reply to Bsimmo

Avatar

It’s a lot clearer even if a fascination for small text, or what seems like small text.
Generally easier to navigate. :-)
Here to what comes.

Avatar

Is it possible to set up redirects—at least maybe from the most-frequented pages on the old paths to the new site?
I know this morning I was a bit surprised when I went to the Compute Module IO Board docs for camera usage (https://www.raspberrypi.org/documentation/hardware/computemodule/cmio-camera.md), and got a 404, with no ability to easily find where it went.
And for at least the short term, all the Google and DuckDuckGo search results for documentation-related things are turning up 404s.
I had to manually navigate around the Pi site to find the new Documentation, then click around in it a while before I found what I was looking for.

Reply to Jeff Geerling

Avatar

Old URLs which began raspberrypi.org/documentation/something should map directly to raspberrypi.org/documentation/computers/something, assuming they’ve not been culled. I’ve asked for a generic redirect for this (see https://github.com/raspberrypi/documentation/issues/1973#issuecomment-895170464), which should catch most links to the old docs, the rest are going to be supported by a more documentation-specific 404 page – see https://github.com/raspberrypi/documentation/issues/1976.

Reply to andrum99

Avatar

Search engines won’t have crawled it yet – it’s a temporary annoyance, but that’s all.

Reply to Liz Upton

Avatar

Search engines will self-repair, yes – but blog posts and tutorials linking to specific pages in the old docs will now have broken links. Which i just know I’m going to be bitten by.

Great to see work on the docs, though. They’ve needed it. :-)

Reply to Jonathan Sanderson

Avatar

And all the Raspberry’s forum posts have all their links broken 💔

Reply to Gonzalo Massa

Alasdair Allan

There now some category-level redirects in place, see https://github.com/raspberrypi/documentation/pull/2010 for more details.

Reply to Alasdair Allan

Avatar

Thanks! As with any major redesign of an existing website, this one had some growing pains, but the worst ones are already being worked over. If you can glance at logs maybe, after a week or so, it might be nice to also add in specific redirects for particular pages getting a ton of traffic to the old URLs.

I typically do that for my own sites just because it will help a number of people to get right to the information they wanted (and helps Google and other crawlers update the links while preserving some of the SEO ranking more quickly).

Reply to Jeff Geerling

Avatar

Great to see the documentation getting a visual refresh as part of this change, to bring it in line with the new website style 😁

Reply to andrum99

Avatar

Is there a specific reason why the restricted section of the PIP contains everything in the public section?

Reply to andrum99

Avatar

Any chance of a search facility for the documentation? Would seem to be a genuinely helpful thing.

Reply to Michael Horne

Avatar

(On the PIP I mean…)

Reply to Michael Horne

Avatar

Will try to get used to the new documentation. My first impression is that pages seem alot longer than the old one. Have to use ctrl f to go to the relevant section I guess.

Reply to Xiang Jiek

Avatar

Looks good. In my opinion https://datasheets.raspberrypi.org/ feels a bit out of place now. And it overlaps some other stuff?

Reply to Diego

Alasdair Allan

In time the documents currently hosted on datasheets.raspberrypi.org will be migrated into PIP.

Reply to Alasdair Allan

Avatar

That’s good. Thanks for replying.

Reply to Diego

Avatar

Nice docs! I noticed around 6PM last night, all the links broke, can we get it redirected?

Reply to James

Alasdair Allan

There now some category-level redirects in place, see https://github.com/raspberrypi/documentation/pull/2010 for more details.

However, links to individual `*.md` pages will not be redirected. We can’t be expected to maintain, forever, a complex tree of links, and then redirect every page when the documentation is restructured, and then again when we restructure it the next time. I’m also about to embark on a large scale cull of the older, less relevant, documentation.

Reply to Alasdair Allan

Avatar

It doesn’t have to be forever, but I think maintaining this and last version is reasonable expectation. Python, for example, has support both for 2 and 3, but not 1. Can you imagine the anguish had Python dropped support for 2 immediately after 3 came into being?

Reply to Harry Hardjono

Avatar

It is good to know about this. I found this post by searching ‘raspberrypi web links broken august 2021’.
One suspects there are hundreds of people out there still puzzled. The 404 is kindof ungraceful. I assumed you had a server go down.
It is much much more than a google update. The Raspberry Pi forums have thousands of links to documentation, which is no longer there. Commercial partners like WaveShare have documentation links on their websites. Lots of developers have bookmarks. These links have been accrued over years.
I would question having the current documentation vanish beneath the waves. One could arrange a deprecation notice or link forwarding.

Reply to Brian Button

Alasdair Allan

There now some category-level redirects in place, see https://github.com/raspberrypi/documentation/pull/2010 for more details.

Reply to Alasdair Allan

Avatar

Whilst I appreciate the need for better documentation and bring the look and feel of the section into line with the web site redesign, but somewhere usability on mobile devices has been forgotten.

Does no one at Pi Towers have a 4″ / 5″ Screen Android 6 or newer SmartPhone to check for how the pages navigate ? It would appear not which is shame because many people do not have access to any other hardware.

Basically it is a mess, to many brainiacs and not enough technophobes making design decisions.

Reply to MW

Avatar

PLEASE, for the love of all things holy, choose a different name for the Product Information Portal. The acronym PIP is already in use, and directly in the path of the Raspberry Pi user base. Pip is the Python package manager, and using “PIP” in a slightly different context will create all manner of confusion, especially with beginning programmers who are trying to sort out all the terminology. I would suggest “Product Information Center” as a substitute (“product information site” would make a rather unwelcome acronym, so that’s right out).

Reply to Steve

Avatar

The new documentation looks good.

One of the things that sets Raspberry Pi apart from certain other products is the quality of the documentation. It’s good to see that this is something that you continue to improve.

Reply to Stewart Watkiss

Avatar

Great work from Raspberry Pi again. Documentation is one of the great strengths of the products and is the reason for the durability of Pi when imitators come out with a bang then disappear quietly.

Reply to Anders

Avatar

This is an excellent improvement!

Reply to William Stevensom

Avatar

Awww… I had grown kinda fond of those old documentation pages that so often graced my confused eyes…
Confused no more they always left me, however, and I am confident the new style will not change that. Thanks, guys.

Reply to wanderer_

Leave a Comment