Dieses Handbuch schreiben

Ein Handbuch zu verfassen ist nicht leicht, vor allem dann, wenn sich das Beschriebene immer weiter entwickelt und es so viel zu beschreiben gibt wie bei museum-digital. Wir setzten deshalb auf Kollaboration und haben uns entschieden dieses Handbuch transparent und für alle potentiellen Autoren offen über GitHub zu schreiben. Zur Gestaltung der entstehenden Seiten greifen wir auf das einfach Markdown zurück. Die darin möglichen Gestaltungsanweisungen finden sich im Internet, bei der Suche nach Markdown cheat sheet z.B. hier.

Vorbereitung

Um an diesem Handbuch mitzuarbeiten ist ein Zugriff auf GitHub nötig. Dafür muss ein Konto (kostenfrei) bei GitHub angelegt werden. Dort sollte, falls schon ein GitHub-Konto besteht, die Funktion "SignIn" gewählt werden, anderenfalls die Funktion "SignUp" zur Neuanlage eines kostenfreien Kontos.

Ist das Konto angelegt und aufgerufen, dann ist es möglich die Handbuch-Seiten (das "Repository") vom GitHub-Server auf den eigenen Rechner zu "klonen. Auf dem erscheinenden Auswahlbildschirm ist die Funktion "Clone a repository from the internet ..." zu wählen.

Danach kann das Repository (also das Handbuch) geklont werden, indem URL (rechts) im erscheinenden Dialogfeld gewählt wird und als Repository URL die Adresse: https://github.com/museum-digital/handbook-de.git angegeben wird. Gegebenenfalls ist auch noch ein Ordner auf ihrem Rechner zu benennen oder anzulegen.

Es erscheint eine Statusmeldung mit Forschrittsleiste, die ungefähr so aussieht ...

Jetzt gibt einmal das originale Handbuch, das sich auf dem GitHub-Server befindet und es gibt zusätzlich eine geklonte Version auf dem eigenen Rechner. Bearbeitungen werden immer auf der lokalen Kopie vorgenommen und müssen dann zum GitHub-Server übertragen werden. Genauso sollte vor jeder Bearbeitung der letzte Stand des Originals auf den eigenen Rechner geholt werden. Für diese Kommunikation und die Abgleiche bietet sich der GitHub-Desktop an, der ebenfalls auf der GitHub-Seite kostenfrei zu erhalten ist. Wenn GitHub-Desktop heruntergeladen wurde müssen nur noch die beiden Enden der Kommunikation eingetragen werden.

Ist die Verbindung etabliert, dann sollte der GitHub-Desktop ungefähr folgendermaßen aussehen:

Wichtig ist, dass oben links unter "Current repository" das museum-digital Handbuch (handbook-de) erscheint. Rechts, in der gleichen Zeile findet sich "Fetch origin". Mit diesem Schalter wird der aktuelle Stand vom GitHub-Server zum eigenen Rechner geholt. Man sollte es sich angewöhnen diesen Schalter gleich nach Start des GitHub-Desktops zu drücken, damit man den jeweils letzten Stand der Dateien erhält und diese statt einer möglicherweise veralteten lokalen Version der jeweiligen Datei bearbeitet.

Alle bisher beschriebenen Aktionen sind nur für die Einrichtung nötig. Von nun an muss stets nur noch der GitHub-Desktop gestartet werden um Bearbeitungen nachzuvollziehen, von GitHub als zentraler Quelle zu beziehen und dort wieder hin zu synchronisieren.