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.