Von Lucy Hattersley und Alasdair Allan

Neue Dokumentationszentrale für Raspberry Pi.

Raspberry Pi hat die nächste Generation seiner Dokumentation vorgestellt, die ab heute verfügbar ist (magpi.cc/documentation). Auf dem Raspberry Pi-Blog (magpi.cc/bringondocs) schreibt Alasdair Allan, Leiter der Dokumentationsabteilung bei Raspberry Pi: „Das Dokumentations-Repository wurde strukturell verändert und vergrößert: Es musste umstrukturiert werden, und ein großer Teil der nicht Raspberry Pi-spezifischen Dokumentation musste entfernt werden, während andere Bereiche unterversorgt waren und erweitert werden mussten."

Die Seite wird automatisch nach einem Push auf den Master-Branch auf der GitHub-Seite erstellt, wo jeder einen Pull-Request erstellen kann.


Markdown 

Alasdair Allan: „Die neue Dokumentationsstruktur stammt von demselben Team, das die hervorragende PDF-Dokumentation für den Raspberry Pi Pico und den RP2040 erstellt hat. Die betreffenden PDF-Dateien wurden auf der Grundlage einer auf Asciidoc fußenden Toolchain erstellt, und wir wussten von Anfang an, dass wir die aktuelle, auf Markdown basierende Dokumentation auf Asciidoc migrieren wollten, denn dies würde uns in Zukunft wesentlich leistungsfähigere Werkzeuge und viel mehr Flexibilität bieten“.

 

Machen Sie mit 

Der Asciidoc-Quellcode für die neue Dokumentationsseite wird auf GitHub gehostet (magpi.cc/documentationgit), und die Dokumentationsseite wird mit Hilfe von GitHub Actions automatisch erstellt und aktualisiert, wenn jemand in den Master-Branch pusht.
„Wir werden jedoch hauptsächlich auf dem Entwicklungszweig des Repositorys arbeiten, der der Standardzweig ist, den man jetzt bei einem neuen Checkout erhält, und auf den man auch für seine Pull Requests abzielen sollte", erklärte uns Alasdair (siehe magpi.cc/documentationpullrequest) und fährt fort: „Wir haben schon immer Pull-Requests gegen den Markdown-Quelltext unserer Dokumentationsseite angenommen. Im Laufe der Jahre, als die Dokumentation wuchs, gab es Hunderte von Mitwirkenden aus der Community, die mehr als 1200 individuelle Pull Requests eingereicht haben und die von der Korrektur kleiner Tippfehler bis hin zur Einbringung kompletter, neuer Abschnitte reichten. Mit der Einführung der neuen Website wird Raspberry Pi weiterhin Pull Requests für die neue Asciidoc-basierte Dokumentation entgegennehmen. Wir werden jedoch etwas gezielter vorgehen bezüglich dessen, was wir in die Dokumentation aufnehmen und versuchen, das Repository auf Raspberry Pi-spezifische Dinge zu konzentrieren, anstatt allgemeine Linux-Tutorials anzubieten.
 

„Wenn Sie bereits zu den Mitwirkenden gehören, ist es am einfachsten, einen neuen Checkout aus dem Repository zu berarbeiten"


Ich hoffe, dass alle, die im Laufe der Jahre zur Dokumentation beigetragen haben, die neue Seite als einen großen Schritt sehen werden, um unsere Dokumentation zugänglicher zu machen - und wie immer akzeptieren wir Pull-Requests. Wenn Sie jedoch bereits einen Beitrag geleistet haben, ist es am einfachsten, wenn Sie das Repository neu einchecken, denn es hat sich viel geändert."