Landing-Page mit Dokumentation zur Nutzung

[andygrunwald]

Hey alle :)

mit meinem kleinen Side-Project (sourcectl) analysiere ich meine Open Source Projekte. Sowie auch dieses. Dabei ist mir aufgefallen, dass die Relation zu Clones und Views recht unausgeglichen ist:

Traffic

Anzeige von Clones / Uniques über Zeit

Anzeige des Traffics als Graph

Zum Beispiel:
In der letzten Woche hatten wir 8 Clones und 130 Views.
Allgemein haben wir deutlich mehr views als clones.
Dies kann (muss aber nicht) ein Indikator dafür sein, dass Leute das Repository finden, jedoch nicht genau wissen was sie damit tun sollen.
Dies könnte besonders auf Studenten zutreffen, die eine Arbeit mit LaTeX erstellen wollen, aber nicht so technisch mit Docker und Co versiert sind.

Die Idee

Eine Landing-Page / Website, die das ganze in einem mehr User-Freundlichen Format beschreibt.
Content an den ich gerade denke:

Table of content

• Allgemeines
  • Was ist das? Was kann man damit machen?
  • Warum ist das sinnvoll?
  • Für wen ist das was?
• "Getting started"
  • Software-Requirements
  • Kompilieren
  • Modifizieren
• Änderungen am Template
• Hilfe bekommen

Mögliche Umsetzung

Um es nah am eigentlichen Code / Repository zu halten, könnte GitHub Pages eine gute Lösung sein.
In Kombination mit einem Static Side Generator wie Hugo (und fertigen Hugo Templates) oder Docusaurus wird auch die Pflege erleichtert und das Deployment automatisiert.

Feedback

@community: Was haltet Ihr davon?
Inbesondere von den Maintainern @ChristianLuxem, @SimonHaak und @Steffeeeen1234 wäre das Feedback interessant.

[ChristianLuxem]

Hey @andygrunwald ,
die Idee finde ich gut. Gegen eine Github Page mit mehr Details spricht aus meiner Sicht nichts.
Die Statistiken würde ich allerdings gerne nochmal verifizieren:
Wie sehen denn die Statistiken in den Monaten aus, in denen normalerweise mehr Hausarbeiten geschrieben werden? Ich würde vermuten, dass die Clone-Zahlen gegen Ende des Jahres ( ab Oktober?) höher sein müssten. Kannst du diese Zahlen auch einsehen?

Das Deployment zu automatisieren ist auf jedenfall eine gute Idee!

[andygrunwald]

@ChristianLuxem Hast du gerade einen Überblick welche Zeiträume dies betrifft?

[ChristianLuxem]

Soweit ich weiß bekommt man die Hausarbeiten doch immer Anfang des Semesters gesagt. Ich würde also vermuten, dass die Hausarbeiten gegen September/Oktober höher sind, eventuell auch noch November/Dezember bei Leuten die etwas später anfangen.
Für das Sommersemester würde ich die Monate März und April analysieren.

[Smidelis]

Hi @andygrunwald,
finde es einer super Idee. Ich denke mir hätte es super geholfen. Hatte zu Beginn des Studiums schon mal dein Template gefunden, aber habe es nicht zum Laufen gebracht und bin dann zurück zu Word. Habe es dann im 4/5 Semester mit etwas mehr Programmier-/Linux Erfahrung nochmal ausprobiert und erst dann habe ich es zum Laufen gebracht.
Befinde mich nun im 7. Semester und habe seitdem alle Hausarbeiten/Scientifiy Essays mit deiner Vorlage geschrieben. Aber selbst bei uns in Wirtschaftsinformatik (B.Sc.) wusste die Mehrheit nichts damit anzufangen. Das größte Problem (wie auch bei mir) war, dass man zu Beginn des Studiums das Template findet, aber noch keine Ahnung hat wie man es nutzt, geschweige denn individualisiert. Nachdem man dann im Studium etwas programmieren lernt und vielleicht auch mit der Shell mehr Erfahrung gesammelt hat, war es den meisten dann trotzdem zum Ende hin zu viel Arbeit sich komplett neu einzuarbeiten. Deshalb finde ich deine Idee super, das ganze etwas besser zu beschreiben/erklären.

Bzgl. deiner Interpretation der vielen Views aber wenigen Clone denke ich, dass die meisten Studierenden keine Erfahrung mit Github haben und sich deshalb nicht trauen über die Plattform einen Clone/Fork zu machen, der evtl. sogar noch öffentlich einsehbar ist. Denke, die meisten finden das Repo und downloaden sich dann erstmal die *.zip (in der Annahme, dass ein Download nicht als Clone gezählt wird).

[andygrunwald]

Danke fürs Feedback @Smidelis.

Die Metriken sind ggf. nicht die stärksten und es sind auch nur Thesen.

Was hätte dir denn im ersten Semester geholfen? Hast du ein paar konkrete Vorschläge?

[Smidelis]

Ich hatte mir die ZIP vom Repo runtergeladen und dann zuerst mit TexLive versucht das zu nutzen, da ich damals noch keine Ahnung von Docker hatte. Habs nicht hinbekommen das zu compilieren, da immer irgendwelche Pakete gefehlt hatten.
Damals war glaube ich aber auch der Docker Part noch nicht so genau beschrieben. Vielleicht ein ELI5 zu den unterschiedlichen Varianten der Ausführung.

Oder dann noch eine bessere Beschreibung zum tatsächlichen "Schreiben". Habs bis heute noch nicht hinbekommen, dass ich in einem Editor wie z.B. TexStudio schreiben kann und gleichzeitig eine "Live"-Vorschau der Arbeit bekomme, da dafür wieder die entsprechenden Pakete installiert sein müssen. Arbeite jetzt mit VSCode und ein paar Tex Pluging. Compliliere es aber jedes Mal neu mit Docker wenn ich das PDF anschauen möchte.

[andygrunwald]

Das ist doch mal super. Sehr hilfreiches Feedback. Danke, @Smidelis.
Eine Frage noch: Wie bist du auf die Vorlage aufmerksam geworden?

[Smidelis]

Ein Arbeitskollege, der gerade seine Master Arbeit geschrieben hatte hat mir schon vor dem Studium davon erzählt und dann haben uns diverse Dozenten der Programmier-Module darauf hingewiesen. Ich glaube Herr Henöckl hat uns im 2. Semester sogar in einer Vorlesung mal ein paar Folien dazu vorbereitet.

[Smidelis]

Was mir eben noch eingefallen ist @andygrunwald.
Ein kleines "Cheat Sheet" für LaTeX. Individualisiert für die Pakete die in deinem Template genutzt werden.
Gibt es zwar im Interne zu Hauf, aber immer sehr allgemein.

Bzgl. der Solution für die Docu sehe ich MkDocs and Read the Docs ziemlich oft. Scheinen eine super Integration mit GitHub zu haben. Kenne mich damit aber leider nicht aus und müsste ich mich erstmal bisschen einlesen.

Man könnte dann noch einen Schritt weiter gehen und Discourse anbieten. Dann wäre es das volle "interaktive" Paket.

Finde es generell eine tolle Idee, hätte super Lust zu unterstützen. Hätte auch die Möglichkeit Services zu hosten, je nachdem wie umfangreich es wird.

[andygrunwald]

Danke!
@Smidelis willst du mich mal unter andygrunwald@gmail.com anschreiben? Ich hab ggf. noch ein paar kleine Fragen die sicherlich mit leichtigkeit beantworten kannst. Danke dir schon mal für den ganzen Input. Der hilft uns!

[markuspoerschke]

Ich finde die Idee super.

Die größte Hürde mit der Latex-Vorlage zu starten ist sicherlich auch die ganze Bedienung dahinter. Vermutlich würde es helfen Tutorials zu den verschiedenen Tools anzubieten. Es gibt ja mitlerweile Cloud-Latex-Tools oder eventuell könnte man es ja auch hier in Code-Spaces zum laufen bringen. Die Website sollte also auch einen Blog- oder Tutorial-Bereich haben.

Ich nutze Docusaurus.io bei einem meiner Open-Source-Projekte, ich könnte da bei der Einrichtung gerne helfen.