This #MagPiMonday, we’ve got another deep dive into the making of Raspberry Pi 5: why writing great documentation for every level is necessary.

When Raspberry Pi Pico was released, people were quick to praise the in-depth official documentation. Writing the docs is a collaborative effort with the engineering and comms team headed up by Alasdair Allan, Head of Documentation. We asked him how they were written.

“How they’re written really depends on what sort of product we’re releasing,” Alasdair says. “For instance, Raspberry Pi 5 is the culmination of several different projects. It has our own silicon on-board, it’s not the main CPU, that’s a piece of silicon from Broadcom. But Raspberry Pi 5 has got our own RP1 chip on-board, and that’s a piece of silicon that talks to all of the on-board peripherals. It talks to I2C, it talks to SPI, it talks to the USB bus, the Ethernet, the cameras, the displays; it’s where all of the peripherals hook into the CPU. So we need a piece of documentation that lets you write kernel drivers, and will allow you to port an operating system to the new Raspberry Pi 5. The documentation needs to be a thorough register level deep-dive, and that means that it’s going to be collaborative effort. Because nobody can hold the whole thing in their head at once.”

At the time we spoke to Alasdair, the peripherals document for RP1 was roughly 1200 pages, but he was hoping to cut that down.

“Beyond that, there’s another strand of work for Raspberry Pi 5, which is the documentation around the board itself,” Alasdair continues. “Raspberry Pi 5 has a number of things that have not been made available before, [such as] PCIe, and there’s other things that are Raspberry Pi 5-specific, and that’s the only documentation I haven’t started writing yet. There’s plenty of time for that, and we’re still waiting for software to settle before launch.”

Window of opportunity

Writing the docs isn’t just about getting the information down – the kind of people looking for that level of info need to be able to understand it, and this is a big part of the philosophy for the docs.

“Documentation is about letting people accomplish a task without making them learn more than they have to do,” Alasdair explains. “What your user wants to do is the thing that they want to do. They don’t care if they accomplish that in a specific computing language, using a specific technology, or specific piece of hardware, they simply want to do the thing they need to do, whether it’s measure temperature, or run a web server, or spin up a file server, [etc.] The task they want to accomplish is the important thing to them. And the documentation and the software under it, and the hardware underneath that, needs to make that as simple as possible.”

For the kind of user knowledge these sections are written for, Alasdair treats these levels as a window.

“ I don’t believe anyone can hold all that in their heads any more. [It’s all about levels of abstraction], you work at the top end, or in the middle, or at the bottom, and the full stack. What you actually work on is a moving window that looks out onto a stack of technology that spans all the way from silicon to high-level languages and protocols. There’s no way that windows reaches all the way to either end. Some people have wider windows, and some have narrow windows. And that’s fine. But nobody can hold the whole thing in their hands.”