htlle-da-vorlage/README.md

HTLLE-DA-Vorlage

Diese Vorlage ist zur Erstellung der Diplomarbeiten an der HTL Leoben gedacht. Bitte sprechen Sie mit Ihren Betreuern ab, ob Sie Ihre Arbeit mit Hilfe dieses Templates verfassen dürfen.

Das hier vorliegende Template sollte die Erstellung von Diplomarbeiten in Teams soweit wie möglich vereinfachen. Deshalb setzen wir auf die Verwendung von freien Technologien welche ohne Lizenzkosten auf jedem Rechner installiert werden dürfen:

• GIT zur Verwaltung und Versionierung der Diplomarbeit.
• Make sowie einige Linux Standardtools zum Aufruf und zur Orchestrierung der Werkzeuge
• Pandoc zur Transformation von Markdown Dateien zu LaTex Dateien, sowie
• BibTex zur Erstellung von Literaturverzeichnissen und Referenzen innerhalb des Dokuments
• TexLive zur erstellung des fertigen PDFs aus dem generierten LaTex Dokument
• Hunspell als Rechtschreibüberprüfung

Zur Erstellung der Arbeit sollte immer das neuest Template aus dem Repository https://itsp.htl-leoben.at/git/Hg/HTLLE-DA-Vorlage.git verwendet werden. Das dort abgelegte Template wird von hg gepflegt und enthält die jeweils letztgültige (und mit der Direktion abestimmte) Fassung.

Wenn Sie Änderungen an diesem Template wünschen, dann erstellen Sie bitte ein Issue in dem sie auf einen ebenfalls von Ihnen aufgegebenen Pull Request verweisen der Ihen Änderungswunsch dokumentiert.

Vorbereitung des eigenen Rechners

Damit die DA gebaut werden kann müssen mehrere Programme installiert sein. Theoretisch funktioniert das auch mit 'purem' Windows, aber einfacher ist es die Arbeit mit Hilfe von Linux zu erstellen. Aus diesem Grund finden Sie hier nur die Anweisungen die sich auf einem Ubuntu 18.04 LTS beziehen.

Wenn der HTL eigene GIT-Server verwendet wird, brauchen Sie die Tools nicht unbedingt installieren und Sie können sich die Arbeit als PDF per E-Mail zuschicken lassen. Mehr dazu weiter unten

Windows

Wenn man Windows 10 als primäres Betriebssystem verwendet hat man zwei Möglichkeiten um zu einer Linux Umgebung zu kommen:

VM installieren

Installation einer virtuellen Maschine auf der ein Linux läuft (z.B: mit HyperV, VmWare, VirtualBox oder einem anderen Virtualisierer) -> Dann erhält man eine VM welche man zum bearbeiten der VM extra starten muss

Windows Subsystem for Linux

Aktivierung des Windows Subsystem für Linux anhand dieser Anleitung welches genau so eine Umgebung erzeugt und bei der die Windows und Linux Welt miteinenader zusammenwachsen.

Es ist egal für welche der beiden Varianten man sich entscheidet - funktionieren werden technisch gesehen beide gleich gut ... wobei die WSL Variante sicherlich mehr Comfort bietet weil damit direkt auf das Windows Dateisystem zugegriffen werden kann.

Das Dateisystem der C:-Festplatte von Windows ist im WSL unter folgendem Pfad erreichbar /mnt/c/. Die Festplatte D: unter dem Pfad /mnt/d usw. Es macht also sinn seine Diplomarbeit gleich auf dem C: Laufwerk anzulegen weil man dann von beiden Welten aus Zugriff auf die Dateien hat.

Damit diese Anleitung für Windows und Linux passt habe ich angenommen dass sie in Windows einen Ordner c:\Diplomarbeit haben der mit folgendem Befehl in das WSL home Verzeichnis verlinkt ist:

$ ln -s /mnt/c/Diplomarbeit ~/Diplomarbeit

Linux

Zuerst müssen (einmalig) die notwendigen Pakete in der Linux Umgebung installiert werden. Dieser Vorgang kann einige Zeit in Anspruch nehmen weil ca. 3-4 GB an Daten installiert werden.

$ sudo apt-get update
$ sudo apt-get install git build-essential make-guile texlive-full pandoc pandoc-citeproc tree rsync hunspell hunspell-de-at

Grundlegende Schritte

Automatisches erstellen einer Diplomarbeit

Um ein privates GIT-Repository mit der HTLLE-DA-Vorlage anzulegen oder diese zu einem bereits bestehenden GIT-Repository in einem Unterverzeichnis hinzuzufügen, können Sie folgenden Link verwenden (ggf. mit LDAP Benutzername und Passwort z.B.: "1911wit00" anmelden).

Das Repository muss dem eingeloggten Benutzer gehören bzw. wird es für diesen erstellt.

• REPOSITORY_NAME setzen Sie bitte den Namen Ihres bereits bestehenden oder neuen Repositories (z.B.: "Diplomarbeit")
• GIT_PATH hier können Sie ein Unterverzeichnis in GIT für Ihre Arbeit angeben

Sie bekommen anschließend eine E-Mail an Ihre Office365 Adresse mit weiteren Informationen und Links zu Ihrem Repository.

Fahren Sie bitte mit dem Befüllen der speziellen Dateien fort.

Build on Commit

Möchten Sie Ihre Diplomarbeit bei jedem GIT-Commit erstellen und an die - in der metadata.yaml genannten - E-Mail-Adressen zuschicken lassen, dann befolgen Sie diese Schritte:

• E-Mail an hg@htl-leoben.at oder lcle@htl-leoben.at
  • Betreff: [Jenkins] Add Build-Job DA
  • Body:
    • Name: [Kürzel von Besitzer]-DA-remote-trigger (z.B.: 199wit99-DA-remote-trigger)
    • Repository: z.B.: https://itsp.htl-leoben.at/git/199wit99/test_da.git
    • GIT Path: z.B.: ./text
    • GIT Branch: z.B.: */master
• Webhook in Gitea
  • Einen Gogs-Webhook zum Repository hinzufügen (Repository -> Settings -> Webhooks -> Add Webhook)
  • Target URL: https://itsp.htl-leoben.at/ci/gogs-webhook/?job=[job-name] (z.B.: https://itsp.htl-leoben.at/ci/gogs-webhook/?job=199wit99-DA-remote-trigger)
  • Secret: secureStudent

Manuelles erstellen einer Diplomarbeit

Wenn Sie mit einer neuen Diplomarbeit beginnen, dann gehen Sie am besten wie folgt vor:

Erstellen eines leeren GIT Repositories in dem Sie Ihre DA Daten verwalten werden.

Es ist prinzipiell egal auf welchem GIT Server sie Ihr Repository hosten. Wir empfehlen dies aber auf dem HTL eigenen https://itsp.htl-leoben.at/git Server zu machen. Sollten Sie Ihre Arbeit auf einem anderen Server hosten, dann achten Sie darauf dass sie ein privates Repository verwenden denn sonst wäre der Inhalt der Arbeit bereits (unabsichtlich) veröffentlicht und beim Plagiatscheck würde Ihre gesamte Arbeit als Plagiat aufscheinen - und in weiterer Folge dann abgelehnt werden. Auch am HTL eigenen GIT-Server kann es aus Plagiats-Gründen ratsam sein, für die Diplomarbeit ein privates Repository zu verwenden.

Fall 1: Sie beginnen mit einem komplett neuen Repository

Das hier gezeigte Beispiel legt ein neues lokales Repository an und verknüpft es mit einem (zuvor uninitialisiert angelegtem) Repository im Internet.

~/Diplomarbeit$ git init
~/Diplomarbeit$ echo "Meine Diplomarbeit" > README.md
~/Diplomarbeit$ git add README.md
~/Diplomarbeit$ git commit -m "first commit"
~/Diplomarbeit$ git remote add origin https://itsp.htl-leoben.at/git/schueler/Diplomarbeit_JAHR.git
~/Diplomarbeit$ git push -u origin master

Fall 2: Sie haben bereits ein eigenes DA Repository mit Daten drinnen

Dieser Befehl klont Ihr bestehendes Repository in das aktuelle verzeichnis.

~/Diplomarbeit$ git clone https://itsp.htl-leoben.at/git/schueler/Diplomarbeit_JAHR.git .

Hinzufügen des Templates als git-submodul

Wenn Sie ein lokales Repo haben, dann wird dieses Repository als git-submodule dazugeklont:

~/Diplomarbeit$ git config core.filemode false
~/Diplomarbeit$ git submodule add https://itsp.htl-leoben.at/git/Hg/HTLLE-DA-Vorlage.git

Der erste Befehl verhindert dass Änderungen an Berechtigungen (wie sie WSL im Hintergrund durchführt) dazu führen dass die Datei als modifiziert angesehen wird. Der zweite Befehl holt das Submodul dazu.

Falls das Template durch hg geändert wird können Sie mit Hilfe des Befehls git submodule update --remote ihre derzeitige Version durch die jeweils aktuellste Version des Templates ersetzen. Damit die Änderungen sichtbar werden müssen Sie natürlich die Diplomarbeit vorher neu bauen.

Auschecken eines Diplomarbeitsrepositories eines anderen Teammitgliedes

Sollten die ganzen obigen Schritte bereits durch eines Ihrer Teammitglieder erledigt worden sein, dann reicht es aus wenn sie sich das Repository inklusive der Submodule einfach klonen.

~/Diplomarbeit$ git clone --recursive https://itsp.htl-leoben.at/git/schueler/Diplomarbeit_JAHR.git .

Erstellen der Inhaltsfiles für die DA

Die Inhaltsdateien legen Sie in Ihrem Repository ab. Am besten Sie beginnen damit, die Inhlatsdateien aus dem Template als Grundlage für Ihre DA zu verwenden. Sie können diese aus dem Template ganz einfach herkopieren und anschließend bearbeiten.

~/Diplomarbeit$ cp -R ./HTLLE-DA-Vorlage/example/* .

Damit sollten sie am Ende dann in etwa so eine Verzeichnisstruktur haben

$ tree ~/Diplomarbeit
.
├── 10-einleitung.md               <= Kapitel: Einleitung
├── 20-zielsetzung.md              <= Kapitel: Zielsetzung
├── 30-ausarbeitungen.md           <= Kapitel: Ausarbeitungen
├── 31-ausarbeitung_schueler1.md   <=          Ausarbeitung Schueler A
├── 32-ausarbeitung_schueler2.md   <=          Ausarbeitung Schueler B
├── 40-zusammenfassung.md          <= Kapitel: Zusammenfassung
│
├── literatur.bib                  <= Das ist das Literaturverzeichnis
├── metadata.yaml                  <= Grundlegende Informationen zur Diplomarbeit
├── ignore.dict                    <= Hier kommen Wörter rein, die beim Spellchecker ignoriert werden (Jenkins-Job)
│
├── img                            <= Hier kommen alle Ihre Bilder rein
│   ├── graph.png
│   └── screenshot_eclipse.png
│
├── pdfs                           <= PDFs für den Anhang (referenziert in metadata.yaml)
│   ├── begleitprotokolle.pdf
│   ├── HTL-DA-Vereinbarung.pdf
│   └── projekthandbuch.pdf
│
│  
└── HTLLE-DA-Vorlage
    ├──                            ... Inhalte aus der DA Vorlage
    └──                            ... wurden hier ausgeblendet

Es ist wichtig dass diese Verzeichnisstruktur so beibehalten wird, weil sonst der Build-prozess schief gehen kann. Achten Sie auf Groß und Kleinschreibung der Dateien und verzeichnisse.

Normalerweise sollten sie mit diesen Dateien auskommen. Sie können den Inhalt dieser Dateien (unter Einhaltung der entsprechenden Formatierungsvorschriften) durch Ihren Inhalt ersetzen. Es ist normalerseise nicht notwendig weitere Dateien einzufügen, denn Dinge wie das Deckblatt, Eidesstattliche Erklärung, div. Verzeichnisse werden automatisch erstellt und gleich korrekt fomatiert.

Hier nochmals eine Erklärung der verschiedenen Dateien:

• Die *.md Dateien im Basisverzeichnis bilden den eigentlichen Inhalt Ihrer Diplomarbeit. Sie können diese Dateien mit jedem handelsüblichen Editor (zur Not auch direkt in Gitea) bearbeiten. Als Sytnax verwenden Sie Markdown mit einigen Spezialfeatures für pandoc. Die Nummerierung am Anfang dient dazu, dass die Reihenfolge in der Diplomarbeit passt. So erscheint z.B: der Inhalt der Datei 20-zielsetzung.md nach 10-einleitung.md und vor 30*.md. Die im Template angebotene Reihenfolge ist jene wie sie in der Diplomarbeit gewünscht ist. Mit dieser Technik kann die Nummerierung der Dateinamen nicht mehr mit der Nummerierung der Abschnitte / Kapitel im Text übereinstimmen, aber das ist in Ordnung. Sie sollten sich im Allgemeinen auf die Namen / Bezeichnungen von Kapiteln / Abschnitten als Bezeichner verlassen und Pandoc selbst, LaTeX die eigentliche Abschnittsnummerierung übernehmen lassen. Die Nummern in den Dateinamen sind Dateinummern in einem für die Shell guten Format und so benutzerfreundlich wie möglich.
• Das /img Verzeichnis beinhaltet alle Grafiken zur Diplomarbeit. Die können hier zur besseren Strukturierung auch gerne Unterverzeichnisse erstellen. Folgendes ist bei der Verwendung von Grafiken zu beachten:
  • Achten Sie darauf dass sie dort nur *.jpg und *.png Dateien ablegen
  • Groß und Kleinschreibung müssen beachtet werden. So werden unter Linux die Datein Hallo.jpg und hallo.jpg als zwei unterschiedliche Dateien angesehen. Unter Windows hingegen nicht.
• Das /pdfs Verzeichnis beinhaltet Dateien welche im Appendix (auszugsweise oder ganz) eingefügt werden. Damit dies geschieht müssen sie aber im metadata.yaml korrekt referenziert werden. Es ist keine Schande hier viele Dateien abzulegen - sofern diese einen Bezug zur Diplomarbeit haben.

Befüllen der speziellen Dateien

metadata.yaml

In dieser Datei befinden sich alle Informationen rund um Ihre Diplomarbeit. Das Dateiformat ist YAML in welchem folgende Felder befüllt sein müssen:

---

# Informationen für das Titelblatt
da-titel: Titel lt. DA Portal
da-jahr: 2020/21 

# Schlüsselwörter werden im PDF als Schlüsselwörter hinterlegt
da-keywords: HTLLE, Keyword1, Keyword2, Keyword3

# Autoren der Diplomarbeit (=Schüler)
# Je Autor sind alle felder asuzufüllen
# Information wird am Titelblatt und bei der Eidesstattlichen Erklärung verwendet
da-author:
- vorname: Joltawan 
  nachname: Barodscheff
  klasse: 5IT
  thema: Subthema des Schülers 1

- vorname: Craig 
  nachname: Tester
  klasse: 5IT
  thema: Subthema des Schülers 2 

# Diplomarbeitsbetreuer
# Je Betreuer sind alle Felder auszufüllen
# Information wird am Titelblatt und bei den PDF Metadaten verwendet
da-betreuer:
- paraffe: hg
  name: Ing. DI(FH) Günther Hutter, Msc.

- paraffe: me
  name: DI Dr. mont Thomas Messner

# Eine Kurzfassung in Deutsch
da-kurzfassung-de: Hier kommt eine deutsche Kurzfassung hin.

# Eine Kurzfassung in Englisch
da-kurzfassung-en: Hier kommt eine englische Kurzfassung hin.

# PDF Dateien die im Anhang zur Diplomarbeit entweder ganz oder nur seitenweise einkopiert werden
# Das Pflichtattribut 'abschnitt' bezeichnet hier die Überschrift für desen Anhang
# Das Pflichtattribut 'pdf-file' ist der Dateiname des PDFs welches im pdfs Ordner zu finden ist (ohne Pfadangabe)
# Wenn man nur einige Seiten aus einem großen PDF einfügen will dann kann man das optionale Attribut 'seiten' verwenden
# in dem man entweder durch Beistrich getrennt szezifische Seiten aufzälen kann oder mittels Bindestrich einen Bereich.  

da-appendix:
- abschnitt: Begleitprotokolle
  pdf-file: begleitprotokolle.pdf    

- abschnitt: Projekthandbuch
  pdf-file: projekthandbuch.pdf

- abschnitt: Technische Dokumentation
  pdf-file: pandoc-manual.pdf
  seiten: 53-73

- abschnitt: Diplomatbeitsvereinbarung
  pdf-file: HTL-DA-Vereinbarung.pdf

da-build-properties:
- build-notification: Diplomarbeit - DA_2021_Thema <269bc6a5.O365.htl-leoben.at@emea.teams.ms>
- build-notification: mytesms@adress.com
---

literatur.bib

Aus dieser Datei wird als Literaturverzeichnis erstellt. Wann immer sie Informationen aus anderen Quellen beziehen oder daraus Wissen ableiten sollten sie diese Quelle zitieren. Alle Informationen zu direkten und auch indirekten Quellen sollten hier möglichst genau dokumentiert werden. Sobald die Quellenangabe dann in der DA verwendet wird, erstellt das Framework einen entsprechenden Literaturverweis.

Egal ob die Quellenangabe aus einem Buch, einer Zeitschrift order irgend einer anderen wissenschaftlichen Arbeit stammt, versuchen sie immer möglichst alle Felder zu befüllen. In diesen bibtex style examples sieht man wie solch eine korrekt befüllter Quelleneintrag aussieht.

Um das Zusammensuchen der Quellenangaben für Bücher zu vereinfachen kann man in vielen Fällen den Bibliographiedienst OttoBib verwenden, in dem alleine durch Angabe der ISBN Nummer eines Buches in vielen Fällen schon einen fertigen BibTex Block bekommt. Einen ähnlichen Dienst bietet die Internetseite bibtexsearch an - wo man durch die Eingabe von Schlüsselwörtern nach BibTexeinträgen suchen kann. Wenn man wirklich nichts im Internet findet, dann kann man sich die Einträge auch selbst basteln - wobei sich die Software JabRef als besonders nützlichlicher Editor dafür herauskristallisiert hat.

ignore.dict

Während des Build-Jobs läuft auch eine Rechtschreibprüfung (hunspell) mit deutschen und englischen Wörterbuch über die Markdown Dateien. Möchten Sie dabei Wörter ignorieren (z.B.: Namen) tragen, Sie diese hier ein. Pro Begriff muss eine Zeile verwendet werden.

Arbeiten im Rahmen der Diplomarbeit

Bauen der Diplomarbeit als PDF Datei

Lokal

Damit das PDF für die Diplomarbeit erstellt wird muss (aus Ihrem Basisverzeichnis heraus) folgender Befehl abgesetzt werden:

make pdf -C HTLLE-DA-Vorlage SOURCEDIR=$(pwd)

Danach erscheint (sofern alles gut geht) die Datei ./diplomarbeit.pdf. Sollte die Datei bereits von einem früheren Lauf her existiert haben wird sie einfach überschrieben. Sollte die Arbeit nicht erfolgreich gebaut werden können, dann kann in der Datei pandoc.log der Grund dafür herausgefunden werden.

Damit Sie nicht immer den gesamten Befehl schreiben müssen können Sie sich auch einen Alias setzen:

alias da="make pdf -C HTLLE-DA-Vorlage SOURCEDIR=$(pwd)"

Damit beschränkt sich Ihre eigentliche Arbeit darauf, die Markdown Files zu editieren (nicht veressen zu speichern) und anschließend den neuen Alias da aufzurufen. Danach haben Sie immer die neuste Diplomarbeit gebaut.

Remote

Sollten Sie die notwendigen Tools (pandoc, LaTeX, etc.) nicht lokal installieren wollen und Sie haben Ihre Diplomarbeit am GIT-Server der HTL versioniert, dann können Sie Ihre PDF auch am Jenkins bauen und sich per E-Mail zuschicken lassen. Es wird dabei immer das aktuellste Template verwendet.

Öffnen Sie dazu den Jenkins-Job und melden Sie sich ggf. mit Ihren Benutzerdaten (z.B.: 1911wit00) an.

• REPOSITORY Ihre Repository-URL z.B: https://itsp.htl-leoben.at/git/1911wit00/Diplomarbeit.git
• GIT_PATH Ggf. der Unterordner in dem sich Ihre Diplomarbeit auf GIT befindet z.B.: diplomarbeit/
• GIT_BRANCH Wenn Sie nicht wissen, was in GIT branches sind, brauchen Sie den Parameter nicht anpassen
• ARCHIVE_FORMAT Wählen Sie aus, ob die fertige Arbeit als .zip oder .tar.gz Datei versendet wird

Beispiel: GIT_PATH ist "text"

$ tree ~/Diplomarbeit
.
├── source
└── text
    ├── 10-einleitung.md
    ├── 20-zielsetzung.md
    ├── 30-ausarbeitungen.md
    ├── 31-ausarbeitung_schueler1.md
    ├── 32-ausarbeitung_schueler2.md
    ├── 40-zusammenfassung.md
    ├── HTLLE-DA-Vorlage
    │   ├──                           ... Inhalte aus der DA Vorlage
    │   └──                           ... wurden hier ausgeblendet
    ├── img
    │   └── graph.png
    ├── literatur.bib
    ├── metadata.yaml
    ├── ignore.dict
    └── pdfs
        ├── HTL-DA-Vereinbarung.pdf
        ├── README
        ├── begleitprotokolle.pdf
        ├── pandoc-manual.pdf
        └── projekthandbuch.pdf

Beispiel: GIT_PATH ist default "./"

$ tree ~/Diplomarbeit
.
├── 10-einleitung.md
├── 20-zielsetzung.md
├── 30-ausarbeitungen.md
├── 31-ausarbeitung_schueler1.md
├── 32-ausarbeitung_schueler2.md
├── 40-zusammenfassung.md
├── HTLLE-DA-Vorlage
│   ├──                           ... Inhalte aus der DA Vorlage
│   └──                           ... wurden hier ausgeblendet
├── img
│   └── graph.png
├── literatur.bib
├── metadata.yaml
├── ignore.dict
└── pdfs
    ├── HTL-DA-Vereinbarung.pdf
    ├── README
    ├── begleitprotokolle.pdf
    ├── pandoc-manual.pdf
    └── projekthandbuch.pdf

Wichtig: Das fertige PDF wird an die E-Mail Adressen aus metadata.yaml verschickt! Die E-Mail Adressen müssen mit "- build-notification" gekennzeichnet sein (siehe oben).

Es muss nicht einmal die Vorlage als GIT submodule im Repository eingecheckt sein, weil hier während des Build Prozesses die aktuelle verwendet wird.

Wichtig: Sie bekommen eine Archiv-Datei (.zip oder .tar.gz) via E-Mail zugeschickt. Dieses Archiv lässt sich mit gängigen Tools entpacken (z.B.: 7-zip). Darin befinet sich:

• diplomarbeit.pdf Ihre fertige Diplomarbeit
• diplomarbeit.pdf.log Der Log Output von pandoc
• spellcheck-results.txt Die vermeintlich falsch geschriebenen Begriffe

Übertragen des aktuellen Standes nach GIT

Es mach Sinn, die Diplomarbeit (auch nach kleinen Änderungen) immer wieder nach GIT zu übertragen. Damit ist sie optimal gesichert und falls Ihre Teammitglieder auch an der DA Arbeiten bekommen sie auch Zugang zum aktuellsten Stand. Falls Sie noch nicht mit GIT gearbeitet haben, stellen die folgenden Absätze eine (ultra-) Kurzeinführung dar.

Git ist ein dezentrales Quellcodeverwaltungssystem bei dem jeder Entwickler eine volständige eigene Kopie der Daten (=Repository) haben kann. Normalerweise holt man sich einen Initialstand von einem GIT Server indem man mittels git clone https://itsp.htl-leoben.at/git/schueler/diplomarbeit.git das entsprechende Repositoiry lokal herkopiert.

Diesen kann man dann lokal bearbeiten und wenn man fertig ist, überprüft man mit git status welche Dateien sich geändert haben. Die geänderten Dateien (und auch solche die neu hinzukommen sollen) markiert man mittels git add gefolgt von den Dateinamen zur Übertragung.

Der Befehl git commit -m "Aussagekräftige Commitmessage damit die anderen sehen was getan wurde" speichert die zuvor markierten Änderungen in das lokale git Repository. Damit sind diese Daten für Sie erstmal gesichert.

Um diese Dateien dann noch an den Server (auf den nach korrekter Einstellung der Berechtigungen alle Zugriff haben) zu übertragen wendet man den folgenden Befehl an git push origin master. Damit werden alle lokalen Änderungen an den Server gesendet.

Jetzt kann es auch vorkommen, dass jemand anders ihnen zuvor gekommen ist, schon Änderungen an den Dateien vorgenommen hat, und diese für Sie am Server bereit liegen. (Anders betrachtet haben sie in diesem Moment eine 'alte' Version Ihrer Diplomarbeit). Diese neueste Version können Sie ganz einfach mit dem Befehl git pull in Ihr Repository übernehmen. Dabei werden sofort alle geänderten Dateien durch die neueren übersetzt und sie können von da weg weiterarbeiten.

Wenn Ihnen die Arbeit mit der Kommandozeile nicht so geheuer ist, dann können Sie (so Ihre Diplomarbeit unter Windows über das WLS erreichbar ist) auch einen grafischen GIT Client wie z.B: TortoiseGit verwenden.

Bei speziellen Fragen zu diesem Vorgehen wenden Sie sich bitte an den Programmierlehrer Ihres Vertrauens.

Tipps & Tricks

Generell

• Man kann ToDo Blöcke in die DA einfügen indem man folgenden Block verwendet \todo{Was noch zu tun wäre}. Diese erscheinen dann als Textblasen am Rand der Arbeit.

Versionsverwaltung

• Vor dem Schreiben: Neuesten Stand vom Server holen
• Nach dem Schreiben: Sofort einchecken und zum Server übertragen
• Verwenden Sie sinnvolle commit Kommentare (Nachrichten)

Text

• Grammatik + Rechtschreibung beachten (Markdown hat keinen Spell-checker integriert). ggf. aspell installieren und durch die Markdown files suchen lassen. Lassen Sie die Dateien remote bauen, so bekommen Sie den Output einer Rechtschreibprüfung mit übermittelt
• Irgendwie sollte man ein (einheitliches) Bild vom Leser haben. Negativbeispiel:
  • Einerseits ein Dummy dem man mdir erklären muss
  • andererseits kann er Python-Pakete installieren
• Formulierungen
  • keine romanartigen Erzählungen
  • keine seitenlange Installationsanweisungen (besser: Link auf Anleitung im Web)
• Es sollte einen roten Faden die Diplomarbeit geben. Dazu erklärt man zuerst die Grundlagen und Inhalte die ein gewöhnlicher Leser braucht um sich in Ihrer Arbeit zurchtzufinden (= zumiest Literaturrrecherche). Danach bauen Sie auf diesen Gurndlagen ihren praktischen Teil auf, welche dann zu einem Ergebnis führt. Aus diesem grund ist die DA üblicherweise wie folgt gegliedert:
  • Aufgabenstellung
  • Grundlagen
  • Praktischer Teil
  • Zusammenfassung
• Bei unterschiedlichen Teilaufgabenstellungen (die womöglich aufeinander aufbauen) ist die Reihenfolge der Ausarbeitungen so zu wählen dass der Leser diesen roten Faden nicht verliert ... Grundlagen zuerst !

Quellcode

• mit Java/Python/*-doc
• Sinnvolle Namen verwenden
• Coderichtlinien einhalten
  • Klassen haben einen Outlline Kommentar (JavaDoc) in dem der Name des Autors und der Zweck der Klasse beschrieben wird
  • Funktionen / Methoden haben einen Outline Kommentar (JavaDoc) in dem beschrieben wird was die Methode macht und was die Parameter sowie der Rückgabetyp bedeuten
  • Gross & Kleinschreibung beachten
    • (final) Konstanten: GROSSBUCHSTABEN
    • packages: immer.mit.kleinbuchstaben
    • variablen: klein
    • Klassen: ErsterBuchstabeGross
  • Benennungen:
    • Funktionen: anhand eines verbs
    • Getter / Setter verwenden
    • Klassen: Einzahl

Listings

• Wenige (aber dafür aussagekräftige) Listings verwenden
• am besten ohne Kommentare
  • dafür mit Erklärung im Text darüber oder darunter
  • mit Verweis auf File
• UML Diagramme als Ergänzung

Bilder

• Machen Sie Grafiken in guter Auflösung (> 72 dpi) und Achten Sie darauf dass diese nicht zu viel oder zu wenig Inhalt zeigen weil die Grafiken auf max. Seitenbreite skaliert werden können und dann entweder zu klein oder zu pixelig erscheinen.
• Orientieren sie die Grafiken so wie sie selbige in der Arbeit haben wollen. Wenn sie Grafiken um 90 Grad drehen, dann drehen Sie alle Grafiken in die selbe Richtung !
• Quellenangaben nicht vergessen (bei selbst erstellen Bildern: 'Eigene Darstellung')

Quellenangaben

• alle Tools inkl. Versionsnummer
• alle Zitate bzw. übernommene Meinungen
• Datenblätter usw. können auch zitiert werden-

Checkliste

Abschließend noch eine kurze Liste der wichtigsten Punkte, an denen erfahrungsgemäß die häufigsten Fehler auftreten. Diese Punkte bilden auch die Grundlage der routine-mäßigen Formbegutachtung an Universitäten.

• Titelseite: Länge des Titels (Zeilenumbrüche), Name, Studiengang, Datum -> Ausbessern in metadata.yaml
• Erklärung: vollständig mit Unterschrift.
• Inhaltsverzeichnis: balancierte Struktur, Tiefe, Länge der Überschriften.
• Kurzfassung/Abstract: präzise Zusammenfassung, passende Länge, gleiche Inhalte und Struktur.
• Überschriften:Länge, Stil, Aussagekraft.
• Typographie: sauberes Schriftbild, keine manuellen Abstände zwischen Absätzen oder Einrückungen, keine überlangen Zeilen, Hervorhebungen, Schriftgröße, Platzierung von Fußnoten.
• Interpunktion: Binde- und Gedankenstriche richtig gesetzt, Abstände nach Punkten (v. a. nach Abkürzungen)
• Abbildungen: Qualität der Grafiken und Bilder, Schriftgröße und -typ in Abbildungen, Platzierung von Abbildungen und Tabellen, Captions. Sind alle Abbildungen (und Tabellen) im Text referenziert?
• Gleichungen/Formeln:mathem. Elemente auch im Fließtext richtig gesetzt, explizite Gleichungen richtig verwendet, Verwendung von mathem. Symbolen.
• Quellenangaben:Zitate richtig referenziert, Seiten- oder Kapitelangaben bei gedruckten Medien
• Literaturverzeichnis: mehrfach zitierte Quellen nur einmal angeführt, Art der Publikation muss in jedem Fall klar sein, konsistente Einträge, Online-Quellen(URLs) sauber angeführt inkl. letztem Betrachtungszeitpunkt
• Sonstiges: ungültige Querverweise (??), Anhang, Papiergröße der PDF-Datei (A4=8.27×11.69Zoll), Druckgröße und -qualität.