Katalogüberarbeitung

[nevrome]

Ich habe den Katalog jetzt noch einmal durchgelesen und auf dem Weg ein paar erste Anpassungen vorgenommen.

Meiner Ansicht nach muss noch einmal eine Überarbeitung dieses Teils erfolgen, da die Bullet-Points mit sehr heterogen Zusatztext erweitert wurden.

Anfangs beschränken wir uns darauf, die Ausgangsfrage mit einigen weiteren Kontextfragen anzufüttern und ein Rezensionstextbeispiel zu geben.

• Wie löst die Software das gegebene Problem? Wie ist die grundsätzliche Funktionsweise konzipiert? Was sind die wesentlichen Bestandteile in Frontend und Backend? z.B. "WebApp als Schnittstelle zu einer Datenbank" oder "Command line interface um ein Neuronales Netz für Nachhersage zu trainieren"

Dann geht diese Struktur aber verloren zugunsten von eher erklärenden Kontextinformationen.

• Ist das Programm mehrsprachig bzw. in welchen Sprachen wird es angeboten? Je nachdem, von wem das Programm eingesetzt werden soll, sollte das Programm in mehreren Sprachen angeboten werden. Üblicherweise wird man das Programm zumindest in einer englischen Fassung erwarten. Sollten verschiedene Sprachversionen getestet werden, so ist darauf zu achten, dass das Layout der Anwendung in den verschiedenen Sprachen weiterhin sichtbar ist. Beschriftungen von Buttons beispielsweise können sich in der Länge des Textes in verschiedenen Sprachen stark unterscheiden, so dass bei schlechter Programmierung der Anwendung ggf. Texte im Benutzerinterface abschnitten sind.

Dieser Trend setzt sich fort und schließt zuletzt auch konkrete Softwarebeispiele ein:

• Gibt es eine Entwicklerdokumentation, sodass die Software leichter verstanden werden und ggf. erweitert werden kann? Essentiell für einen Entwickler, der sich mit der Erweiterung oder Nutzung einer Software befasst, ist es, ihm einen möglichst einfachen Einstieg zu bieten. Dafür ist eine aussagekräftige README Datei notwendig, die kurz die Verwendung des Programmes mit den Standardeinstellungen demonstriert. Ein Beispiel dafür ist Bibtex_JS. Idealerweise werden noch Beispieldaten für ein besseres Verständnis des Programmablaufs beigelegt und ggf. weitere häufig verwendete Anwendungsfälle der Software in Beispielen vorgestellt. Auch dies kann das genannte Beispiel demonstrieren Bibtex_JS Beispiele). Abhängig von der Komplexität der Software kann es sinnvoll sein, ein ggf. auch von einer Nutzercommunity gepflegtes Wiki bereitzustellen, um fortgeschrittene Optionen zu erläutern (siehe Bibtex_JS Wiki).

Meiner Ansicht nach muss bis zu einem gewissen Grad vereinheitlicht werden, um dem Leser ein in jeder dieser Fragen in etwa das selbe Set an Informationen zur Verfügung zu stellen.

Wir haben unter anderem folgende Textbausteine zur Auswahl: erweiterte Fragen, ausführende Texte, Softwarebeispiele, Rezensionstextbeispiele. Welche sollen überall vorkommen?

Ich schlage vor, die ersten Punkte vom Stil her an die untere anzupassen, die unteren aber deutlich zu kürzen. Wenn der Entwicklerteil doppelt so ausführlich wie der Anwenderteil ist, dann schreiben wir am Publikum vorbei.

[situx]

Ich finde das ist ein wichtiger Punkt. Ich habe in meinem Teil wo möglich versucht relativ ausführlich Beispiele zu geben gerade auch weil das Zielpublikum ggf. viele Begriffe nicht umgehend versteht, fände es aber auch besser wenn wir da einheitlicher vorgehen würden. Wie ist denn eure Meinung was eine optimalere Länge wäre? Sind die technischen Erläuterungen zu ausschweifend oder genau richtig um den Sachverhalt darzustellen?

[archaeoklammt]

@situx Nein, mir gefällt es gut, das es unten so gut erklärt wird. Weil ich als Archäologin jetzt wirklich besser verstanden habe, was Aspekte sind, die Software ausmachen, und ich habe mir im GithubRepo der Spatial API angeschaut, ob ich Hinweise auf einen Buildprozess finde.

[nevrome]

Wenn unten nicht gekürzt werden soll, dann muss zumindest oben noch etwas ausformuliert werden. Ich kann mich da auch gerne einbringen.

[nevrome]

Ich merge jetzt, um weiteren Abweichungen zwischen PR und Master vorzubeugen.