Читать книгу GitHub – Eine praktische Einführung - Anke Lederer - Страница 20

Bei GitHub gibt es eine Konvention bezüglich des Dateinamens README.md. Sobald sich eine solche Datei entweder im Hauptverzeichnis (auch Wurzel- oder Root-Verzeichnis genannt) oder in den Unterordnern docs oder .github (den Punkt vorweg beachten!) befindet, interpretiert GitHub diese als »Willkommensseite« und zeigt deren Inhalt den Besuchern des Repositorys an.

Idealerweise sollte in der Datei eine Reihe von Fragen zum Projekt beantwortet werden wie:

 Was macht das Projekt, und warum ist das irgendwie nützlich?

 Wie benutzt man das Projekt (z.B. wie installiert und konfiguriert man die Software)?

 Was kann eine Anwenderin machen, wenn sie Hilfe braucht?

 Eventuell: Wie kann man das Projekt unterstützen und in welcher Form?

 Eventuell: Wo findet man weiterführende Informationen?

 Eventuell: Wer entwickelt und betreibt das Projekt?

Die Endung md steht übrigens für »Markdown«. Das ist eine Auszeichnungssprache mit simplen Anweisungen, um optische Anpassungen und Formatierungen wie Überschriften, Fettschrift und Aufzählungszeichen zu erzeugen oder um Bilder einzufügen und Links zu setzen. Die Überschrift »The Moby Project« in Abbildung 2-3 kann man beispielsweise wie folgt erzeugen⁸:

# The Moby Project

Gute Auflistungen gängiger Befehle und wie deren Darstellung aussieht, findest du im Internet.⁹ GitHub selbst bietet auf seinen Hilfeseiten ebenfalls weiterführende Informationen an.¹⁰

Vorlagen für eine gute README.md gibt es natürlich auch, beispielsweise unter https://gist.github.com/jxson/1784669.

Tipp: Man kann übrigens auch in Unterverzeichnissen jeweils eine README.md anlegen. In diesem Verzeichnis wird sie dann ebenfalls als Willkommensseite angezeigt.

Jetzt sich kann die interessierte Anwenderin ab sofort glücklich und wissend zurücklehnen.

Aber hoppla, was macht die interessierte Anwenderin, wenn das Projekt gar keine README.md anbietet oder diese Datei nur spärliche Angaben enthält? Projekte können ein Wiki haben, in dem weitere Informationen enthalten sein könnten (zu finden in Zeile 1 in Abbildung 2-2). Nach meiner Erfahrung ist es jedoch eher unwahrscheinlich, dass es ein gut dokumentiertes Wiki gibt, aber keine Willkommensseite. Einen Versuch ist es dennoch allemal wert.

Tipp für eigene Projekte Wer möchte, dass sich die Menschen schnell im Projekt zurechtfinden, befüllt die README.md entsprechend aussagekräftig.

Keine README.md, kein Wiki – und nu? Jetzt hängt es davon ab, wie wichtig es der interessierten Anwenderin ist, eine bestimmte Information zu erhalten. Will sie sich z.B. über einen Fehler informieren, lohnt sich ein Blick in das Register Issues, zu Deutsch »Thema«, »Frage« oder auch »Angelegenheit« (siehe Abbildung 2-4, die Zahl zeigt die derzeit offenen Issues an). Ein Issue ist eine Art offener Brief an die Projekteignerin oder deren Maintainer und soll Handlungsbedarf aufzeigen. Der Handlungsbedarf kann sich auf Fehler beziehen, aber auch Wünsche für weitere Funktionen (sogenannte Feature-Requests) oder Anmerkungen darüber, wie beispielsweise eine fehlende Willkommensseite, sind üblich. Issues können kommentiert werden, und es kommt dort häufig zu regen Diskussionen. Mit etwas Glück findet die interessierte Anwenderin hier die Lösung für ihr Problem. Leider gibt es dafür keine Garantie, aber immerhin die Chance.

Abbildung 2-5 zeigt die Issues-Seite, auf der die interessierte Anwenderin suchen, filtern, Fehler melden oder sich Issues anschauen kann. Man beachte das vorausgefüllte Textfeld, in dem is:issue is:open steht. Das ist das Suchfeld. Da sie auf das Register Issues geklickt hat, nimmt GitHub an, dass sie an Issues interessiert ist (is:issue) und dass mit hoher Wahrscheinlichkeit die noch offenen für sie im Moment interessant sind (is:open). Diese beiden vorausgefüllten Filter können jederzeit gelöscht und/oder um eigene Suchwörter ergänzt werden. Um Antworten auf eine Frage zu bekommen, empfiehlt es sich, nach Issues Ausschau zu halten, die entsprechende Suchwörter enthalten und in denen rege diskutiert wird. Ob in dem Issue diskutiert wird, erkennt man an einem Sprechblasensymbol auf der rechten Seite. Die dort aufgeführte Zahl ist die Anzahl der Kommentare.

Abbildung 2-4: Im Register Issues besteht eine gute Chance, hilfreiche Informationen zu finden.

Abbildung 2-5: Bei den Issues gibt es vielfältige Filter- und Suchmöglichkeiten. Auch sieht man auf einen Blick, bei welchem Issue viel diskutiert wurde bzw. wird.

Sollte die interessierte Anwenderin hier immer noch nichts finden, hilft häufig nur noch eine Webrecherche¹¹, um außerhalb von GitHub hilfreiche Informationen zu finden. Es gibt viele Foren im Internet, und mit etwas Glück unterhalten sich andere Menschen dort genau über das gesuchte Thema.

	Tipp: Forum Stackoverflow Meine Lieblingsseite für Fragen über Software im Allgemeinen und Softwarecode im Speziellen ist Stackoverflow12. Es gibt dort viele kompetente Menschen, die ihr Wissen gern teilen.
	Der Clou ist in meinen Augen aber das ausgefeilte Bewertungssystem, das dafür sorgt, dass die am besten bewertete Antwort auf eine Frage ganz oben angezeigt wird. Nie wieder langes Scrollen durch wenig hilfreiche Beiträge, das Wichtigste steht immer oben.

Im schlimmsten Fall gibt es aber keine Informationen, und die interessierte Anwenderin muss auf Alternativen ausweichen. Beispielsweise kann sie versuchen, mit einem Softwarefehler zu leben, oder sie sucht sich eine andere Software, die einen ähnlichen Funktionsumfang hat.