Dokumentation v7 und v6.2 in neuer Struktur

Hallo ihr Docs,

diese Struktur http://docs.linuxmuster.net/de/v7/ wurde von mir vorgestellt und mit, soviel ich mich erinnere positiver Reaktion angenommen.
Zusätzlicher Vorschlag war, ob man die v6.2 nicht auch schon auf diese Struktur bringen könnte.
Prinzipiell finde ich die Idee nicht schlecht, man muss halt nochmal 1-2 Stunden Arbeit reinstecken. Vorteil: man hat sich für die v7 schon dran gewöhnt.

zusätzlicher request: bitte ganz klar in RTD-template kennzeichnen, dass es sich um die 7 handelt, z.B: den string “Docs” ganz oben durch “Docs v7” bzw., “Docs v6.2” ersetzen. Genauso auch die Farbe des strings “v7”/“v6.2” in der linken sidebar andersfarbig machen/hinterlegen.

VG, Tobias

Hallo Tobias!

diese Struktur http://docs.linuxmuster.net/de/v7/ wurde von mir vorgestellt
und mit, soviel ich mich erinnere positiver Reaktion angenommen.
Zusätzlicher Vorschlag war, ob man die v6.2 nicht auch schon auf diese
Struktur bringen könnte. Prinzipiell finde ich die Idee nicht schlecht,
man muss halt nochmal 1-2 Stunden Arbeit reinstecken. Vorteil: man hat
sich für die v7 schon dran gewöhnt.

+1!

Wollte mal schnell ein fehlendes Wort bei der Einführung ergänzen. Das "zur"
fehlt bei “stehen .* zur Seite. .*” Dabei habe ich festgestellt das der “Edit
on Github” nicht zur Bearbeitung führt. Github meldet 404.

Beste Grüße

Thorsten

Hallo Thorsten,

Leider ein Bug auf Seiten von ReadTheDocs, wenn du “origin” aus der URL löschst funktioniert es wunderbar…siehe Beitrag #12 in Kapitel Computeraufnahme: Tutorial für git :)

VG, Tobias

Hey,

ich habe das jetzt mal umgesetzt in einem eigenen branch und damit in einer eigenen Version auf readthedocs:
http://docs.linuxmuster.net/de/v6.2/

Jetzt sollte, bevor grossartig weiter dokumentiert wird, beschlossen werden, ob wir das so wollen.

Man muss halt in Kauf nehmen, dass viele Links auf ask.linuxmuster.net angepasst werden muessen, wenn das dann in der gleichen struktur in http://docs.linuxmuster.net/de/latest/ zu sehen sein wird.

VG, Tobias

Hallo Tobias!

Ich dachte der Beschluss, das wir das so wollen, sei schon gefallen. Ich für meinen Teil würde es wollen. Letztendlich denke ich aber, das D-Team entscheidet das in eigener Regie!

Schön wäre es, wenn der [Edit on Github] - Button wieder funktionieren würde. Das liegt aber leider nicht in unserem Einflussbereich, wenn ich das richtig verstanden habe.

Ich dachte daran, dass man die Community zu einer “Jagd den toten Link” aufrufen könnte. Wer die meisten Links bis zum Tag X berichtigt, bekommt einT-Shirt oder so. Vielleicht wäre das eine Werbemaßnahme und es finden sich dann mehr Leute, die sich aktiv an der Doku beteiligen.

Beste Grüße

Thorsten

Di idee ist nicht schlecht. Die meisten toten Links wird es aber nicht in der Doku selbst geben sondern in alten Threads in ask.linuxmuster.net und die Posts von anderen kann ja nicht jeder korrigieren. Aber damit müssen wir leben… oh, ich sehe grade:
http://docs.readthedocs.io/en/latest/user-defined-redirects.html#page-redirects
im prinzip könnte man das machen, aber watt fürn Aufwand!

VG, Tobias

Hallo Tobias,

ggf. kann man auch darüber nachdenken, die Links in Ask per Skript zu ändern. Ich vermute, dass disourse Beiträge nicht dateibasiert speichert, sondern in einer Datenbank, das macht das Ganze etwas umständlich.

Grüße,
Sven

Hi Sven,

wenn ich es auf der Tagung richtig verstanden habe, liegt es ja in einem Docker-Container und dann noch extern gehostet. da haben wir vermutlich kurzfristig pech.
Vg, Tobias

Hallo Tobias,

ich würde den Zweig nicht v7 nennen, sondern v7.0, sonst haben wir mit Erscheinen der Version 7.2 wieder das Problem toter Links, oder übersehe ich da etwas?

Grüße,
Sven

1 Like

Hallo Sven,
in der Tat: wenn Version v7.2 eine neue Version ist, die man neu dokumentieren muss, dann ja.
Wenn die v7 so ein rolling release ist, wie es die v6.0+v6.1+v6.2 eigentlich war, dann wäre v7 sogar besser.

Es hat sich zwischen v6.0 und v6.2 mäßig viel getan, was die Doku geändert hat, aber ja, eine neue Version der Doku hätte (bei vollständigkeit) wohl gut getan (neue screenshots von linbo-grün nach linbo-blau, änderung bei bind-mounts vs. jetzt usw.)

Also: v7.0 nennen. Ok?
Vg, Tobias

Links sollten in der Regel immer nach /latest/ gehen. Dieser Link zeigt dann immer auf die aktuelle Doku.

v7 oder v7.0 ist eigentlich egal, da es beim Release nach /latest/ gemerged wird.

1 Like

Hallo!

Die Frage die wie vorher klären sollten:

Warum sollte es eine v7.0 Dokumentation noch geben wenn die v7.1 released wurde. Wollen wir uns das antun wieder verschiedene Versionen zu dokumentieren, parallel? Ich würde den Standpunkt vertreten, dokumentiert wird das was gerade aktuell ist. Beim Release ein Snapshot als PDF u.ä. der alten Doku, das wird dann online gestellt. Wer nicht updated hat dann eine Anlaufstelle. Fertig!

Meine Meinung!

Aber vielleicht jetzt wo Stephans Post gerade reinkamm, ist sogar das nicht nötig.

Liebe Grüße

Thorsten

Hallo Stephan, hallo Sven,

ihr habt ja beide recht. Ich vergaß, dass es ja /LANG/latest gibt, was tatsächlich für die aktuelle Doku spricht.
Wenn es aber so weitergeht, wird es vllt. noch eine Weile nötig sein, die v6.2 zu hosten.
Das würde dann in einem branch mit diesem Namen gehen.
Insofern sind links, die jetzt jemand zu einem Thema bisher schrieb ab der v7 sowieso nutzlos: Dann wird es vermutlich ganz anders gehen. Wenn jemand mit einer v7 auf ein ask-thread stößt, der auf latest/howtos/install-on-xen verweist wird er eben ein 404 bekommen.
wir sollten aber ganz dominant auf die Umstellung hinweisen und monitoren, ob es nötig wird die redirects einzupflegen. Die funktionieren unter readthedocs nur, wenn man eine 404 bekommt.

VG, Tobias

Hi zusammen,
nachdem es schon ein paar Strukturänderungen gab und ihr sie verkraftet habt, hier noch eine Umfrage, ob ihr folgende Änderungen noch für sinnvoll und nötig haltet:

schaut mal
http://docs.linuxmuster.net/de/latest/systemadministration/network/subnetting-basics/index.html#vorbemerkungen

vs.

http://docs.linuxmuster.net/de/latest/systemadministration/network/coovawifi/chillispot-preparation.html

an. Die obere Dokumentation ist fürs Subnetting. Es gibt keine “Next” + “Prev” Knöpfe mehr am ende eines Abschnitts, weil alles auf einer Seite ist. Das (meinem Empfinden nach) bessere Leseerlebnis ist, dass das Inhaltsverzeichnis auf der linken Seite jetzt stehen bleibt und somit alle Themen dieses Kapitels schnell erreichbar / überspringbar sind.
[Edit:] ich stelle fest, das passiert erst dann, wenn man einmal eine Überschrift des aktuellen Kapitels im Inhaltsverzeichnis anklickt. Sonst scrollt das Inhaltsverzeichnis auch erstmal weg. [/Edit]

Im Gegensatz dazu: die untere Doku für den Coova-Chilli. Es gibt mehrere HTML-Seiten, die alle mit Next + Prev erreichbar sind. Manche sind kürzer und manche länger. Bei den längeren fällt auf, dass die Navigationsleiste einfach mitscrollt (außer wenn man unterüberschriften auf der aktuellen Seite anschaut) und somit der Überblick etwas verloren geht. [Edit:] Das bleibende Inhaltsverzeichnis gibt es hier auch, aber eben nur für die aktuelle Seite - und die verlässt man oft viel schneller [/Edit]

Wenn wir etwas ändern werden schon wieder ein paar links ungültig, die man als Supporter im Forum bisher gepostet hat, z.B. gab es eben früher:
http://docs.linuxmuster.net/de/latest/systemadministration/network/subnetting-basics/switch-konfiguration.html
das ist jetzt eben:
http://docs.linuxmuster.net/de/latest/systemadministration/network/subnetting-basics/index.html#konfiguration-des-l3-switches

Daher die Umfrage: was findet Ihr, wie es navigierbar sein sollte:

  • Ändern: Pro Kapitel nur eine große Seite
  • Lassen: Pro Kapitel mehrere (kleinere) Seiten

0 Teilnehmer

[Edit:] yo, vielleicht sind diese Überlegungen wirklich nur details und nicht sooo wichtig [/Edit]

VG, Tobias

Ich finde eigentlich lange Seiten besser – kann aber nicht beurteilen, wie viel Aufwand die Änderung wäre. (Daher stimme ich vorerst nicht ab.)

Das kann man doch über redirects lösen, oder? Ich weiß jetzt nicht wie aufwendig das ist, aber das kann man bestimmt auch mit einem Skript lösen.

vG

Moin!

Schließe mich Michael voll und ganz an!

Beste Grüße

Thorsten

ihr dürft gerne abstimmen, das ist nicht automatisch ein Arbeitsauftrag :slight_smile:

ich fand die redirects in readthedocs nicht ganz intuitiv und keine möglichkeit gesehen die per skript zu erstellen.
Man kann ja vllt. sphinx-build dazu bringen das entsprechende html mit redirect zu produzieren, (vielleicht ist es das was du meintest).
VG

Uralter Thread, aber FYI:

Ich werde die v7 jetzt noch in kleinigkeiten ändern, nämlich:

aus
http://docs.linuxmuster.net/de/v7/getting-started/prerequisites/index.html

wird jetzt

http://docs.linuxmuster.net/de/v7/getting-started/prerequisites.html

die zum eigentlichen Kapitel zugehörigen ./media Unterordner landen dann halt alle in einem Unterordner
getting-started/media/

und wenn es da mal dateinamen-konflikte gibt, kann man die ja beheben.

VG, tobias

wo ihr es jetzt schon sehen könnt:

http://docs.linuxmuster.net/de/v7/about/release-information/index.html
wird gleich
http://docs.linuxmuster.net/de/v7/about/release-information.html

heißen.
VG, Tobias