IMPORTANT: DOCUMENTATION REPO UPDATE

[aallan]

All,

We're in the process of transitioning the documentation from the current Markdown-based source format to Asciidoc. This will help us automate the creation of a new and improved documentation site which will fit with the newer website styling and have much improved navigation.

In the process, we will also be addressing structural issues and reducing the overall amount of documentation (e.g. see #1810) to reduce the overall load in maintaining the documentation site. The original documentation was created when there was a lot less third-party content around to support the Raspberry Pi, and we're going to be removing a fair chunk of the existing text that really isn't relevant anymore, and better dealt with elsewhere on the web. The core documentation will remain, but a great deal of non-Raspberry Pi specific documentation will be removed.

As much as possible we'll also be removing references to third-party products, and the policy going forward is that we won't be recommending specific tools other than things that ship with Raspberry Pi OS.

At some point soon — probably around the end of June, beginning of July — we will freeze the current documentation repo. After that time contributions and PRs based on the Markdown source will not be accepted, and any PRs that are still open will be closed.

There will then be some rearranging behind the scenes and afterwards the current Markdown-based documentation repo will be replaced with an Asciidoc-based equivalent. We're intending to transfer (relevant) Issues from this repo to the new repo, but all PRs will be lost.

The freeze while we sort things out behind the scenes should hopefully not be more than a couple of weeks. Contributions based on the new Asciidoc-based source will be welcomed after the transition is made public. However one priority going forward will be to keep this documentation site much leaner than its current form, so large additions, or new documentation topics, will face additional scrutiny.

[UNIVAC-Colonel-Panic]

We're in the process of transitioning the documentation from the current Markdown-based source format to Asciidoc. This will help us automate the creation of a new and improved documentation site which will fit with the newer website styling and have much improved navigation.

Could you elaborate a bit more on what triggered the transition? Maybe a simple list of pros/cons you've encountered? I'm especially interested in knowing how the switch brings automation and better navigation. Did you consider any other alternatives besides Asciidoc?

I help update documentation for an open source project and I'm always on the lookout for ways to improve documentation maintenance. The docs were originally done with LibreOffice as a single .odt file -- a mixed text and binary format. The transition to Markdown greatly improved the ability to compare changes, a huge advantage over LibreOffice's cumbersome "track changes" feature.

I'm not intending to take up a lot of your time but I thought your insight and experience in switching from Markdown to Asciidoc would be helpful to know.

[JamesH65]

The documentation has been in need of a revamp for some time, but until recently we have not had the manpower to do it. We now have a docs manager, @aallan so now it's time to sort it out.

ASCIIDOC was used for the Pico documentation. It's relatively comprehensive, with more options than markdown, and it's also fairly easy to automate the various conversions required to get from ASCIIDOC to things like PDF, HTML and ePub. So we can have make files that go from the ASCIIDOC to all our required outputs.

We are also able to convert the current markdown to ASCIIDOC automagically fairly easily (still work in progress).

[aallan]

Just to update folks if they're following along. I'd anticipate freezing the current documentation for PRs at the end of this week. It'll then be a couple of weeks while we do some behind-the-scenes stuff, and then I'd anticipate swapping out to the new Asciidoc-based documentation around the end of the month. We'd still be working on things — flattening the documentation down and pruning the excess — but it'd be more or less ready for the public and releasing it then will let folks see how things work and get their heads around the Asciidoc format. I'd anticipate opening things back up for PRs a couple of weeks after that, so middle of August.

[aallan]

This repo is currently "frozen" and the infrastructure that connects it to raspberrypi.org/documentation has been severed. There may be a number of updates to this repo over the next few days that appears to break things. These are being done to help along the automatic markdown to asciidoc conversion.

I'd expect the new generation documentation to get cloned into this repo and be open for business on or around the 9th August. Thanks for you patience!

[aallan]

This is just to confirm that the new asciidoc-based documentation — and documentation site — will go live on Monday 9th August baring calamities.

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 will be accepting pull requests against the new source. However, if you're already a contributor the easiest thing to do is for you to take a fresh checkout of the repository because things will be changing dramatically overnight (well, over morning. Things will be flipping in the AM).

Going forward we'll also be working on a new develop branch, which will be the default branch for the repo and where you should target your PRs. The master branch will be protected, and merges to master will trigger a rebuild of the actual documentation site on raspberrypi.org.

[aallan]

Welcome to the new documentation site. There will be a blog post later today (a couple of hours maybe) which will give more information. But…

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

If you’re already a contributor, the easiest thing to do is to take a fresh checkout of the repository, which will give you a clean copy of the develop branch because things have changed a lot today.