wartbarere Hilfeseiten
Die Hilfeseiten von Dozentron sind nicht ganz intuitiv wartbar (Tutoren benötigen momentan zur Erstellung immer die Hilfe eines Dozentron-Beauftragten, der die Markdown-Dateien in Dozentron einpflegt).. Das Erstellen von Markdown und anschließendem einbetten in slim Templates finde ich unschön und könnte besser funktionieren.
Da kamen mir jetzt 2 konkrete Einfälle:
-
Wir benutzen als Hilfeseiten einfach das Wiki des Dozentron-Repositories. Da steht ja eh schon Entwickler-Hilfe drin. Dann ändern wir nur die Links auf den HELP ME Buttons. Hätte aber den Nachteil, dass man für die Hilfe auf einer komplett anderen Seite landet.. Könnte verwirren?.
-
Wir erstellen eine Subroute, die Markdown-Dateien aus einem Ordner ausliefert. Das hätte den Vorteil, die Doku ist versioniert, sie besteht aus einzelnen Markdown-Dateien und man kann das ganze ins gewohnte Dozentron-Seitenlayout embedden: Die URI
dozentron.de/doc/java/teacher-help.md
würde dann auf den Pfad
{RAILS.root}/doc/java/teacher-help.md
gemapped werden.
Verlinkungen innerhalb der Markdown-Dateien sollten auch funktionieren, wenn sie relativ angegeben werden und der HTML-Root (wie auch immer dieses Attribut heißt??) auf dozentron.de/doc
steht.
Die Verzeichnisse würden dann so aussehen:
- Gemfile
- app/
- doc/
- java/
- teacher-help.md
- student-help.md
- python/
- teacher-help.md
- student-help.md
- about.md
- index.md
Der 2. Fall wäre nicht viel Aufwand, lässt sich relativ billig mittels Routing-Wildcards lösen und ist IMO die schönere.
@cslz90 , @dalt40 Meinung dazu? @dalt40 gibt es einen wichtigen Grund, warum die Hilfeseiten slim Templates mit embedded Markdown sind?
EDIT: Kann dann auch Asciidoc sein, da auf lange Sicht wohl Asciidoc (#54 (closed)) benutzt werden soll..