Doku braucht evtl. bug-fix Abschnitt

Weiterentwicklung Dokumentation
#1

@dokuteam: @cweikl, @toheine, @MachtDochNix
wir brauchen einen Abschnitt in der Doku. Ich habe mal hier: https://docs.linuxmuster.net/de/latest/systemadministration/maintenance/keep-lmn-uptodate.html einen link hierauf:
https://docs.linuxmuster.net/de/latest/about/release-information.html
erstellt. Also auf die Release-Information. Dort commite ich mal eine Lösung.

Mir gefällt das aber nicht so richtig, die Liste kann beliebig lang werden, evtl. sollte man eine eigene Seite dafür einplanen.

Evtl. nehmen wir das auch aus der Haupt-Doku raus und pflegen solche Anleitungen für Fixes hier in ask.linuxmuster.net - aber dann muss man sich am Riemen reißen, die User nicht mit der Komplexität von ask zu überwältigen. Immerhin gibt es vllt. Leute, die die Lmn am Laufen haben, aber nicht in ask beteiligt sind, aber dennoch ja die Fixes finden müssen.

Vg, Tobias

Fehlerhafte Einträge in smb.conf
#2

eujin ticket dazu erstellt:

#3

Hallo Tobias,
wären solche Infos ggf. nicht auch im Wiki sinnvoll.
Das Wiki müsste aber natürlich aufgeräumt werden …
VG
Chris

#4

Hallo,

die Infos, die hier stehen (https://docs.linuxmuster.net/de/latest/about/release-information.html) könnte man in eine neue Seite machen (z.B. docs…/was-ist-neu.html).

In die Release Informationen, würde ich wirklich nur die Release-Infos schreiben und zwar so, dass immer die neusten Sachen oben stehen.

vG Stephan

#5

Hi Chris,
wir haben mal vereinbart, dass das Wiki eher als „Doku der Community“ angesehen werden soll, also evtl. weniger zuverlässig bzw. offiziell als docs.linuxmuster.net. Natürlich könnten wir angesichts der Disusssion um ein Community-Projekt und dem Stellenwert der Community wieder darüber diskutieren, eine „Fix-Release-Wiki-Seite“ einzuführen, so dass wirklich die COmmunity dann auch die Doku darein schreiben kann. Dafür wird ja quasi ask zur Zeit „missbraucht“.

du meinst, dass Release-Infos also nur aktuelle (und dann anschließend alle älteren) News enthält, was es zu tun gibt?
Und „was neu ist“ ist sozusagen gar keine Release-Information?
Ok, könnte man machen.

Die Abschnitt 3 + 4 „was erhalten bleibt“ und „was es nicht mehr gibt“ … weiß auch nicht, ow man die dann hinstecken sollte.

Vgt, tobias

#6

Alternativ-Vorschlag: In der Doku unter dem Bereich „Systemadministration“ eine Sub-Kategorie: Bekannte Probleme, Fixes und Workarrounds schaffen? Nur so ne Idee.

#7

Ja und Ja :slight_smile:

Entweder ganz weg oder hier mit an Ende? (https://docs.linuxmuster.net/de/latest/about/about.html)

vG Stephan

#8

Also, das wäre die Variante, die Stephan vorschlug:
image

#9

Danke, Tobias. IMHO gehören die „Gefundene und behobene Probleme“ mit zu den Release-Infos. Also ungefähr so:

Version 1.0

Neue Funktionen / Features

  • xy

Behobene Probleme

  • Bug 1 (am besten mit Link zum Issue bei Github :))
  • Bug 2

Besondere Hinweise / Upgradeanweisungen

  • Bitte xy ändern
  • Bitte z und v beachten
  • etc.

Version 0.9

analog

Grundsätzlich müsste man überlegen, wer die Release-Infos hauptsächlich schreibt. Ich denke, dass das Aufgabe der Entwickler ist und das Dokuteam eher ergänzt. Github hat ja auch ein Release-Feature, was man nutzen könnte (zumindest die Entwickler) und das Dokuteam kopiert die Infos einfach in die Doku. Verstehst du was ich meine?

vG Stephan

#10

Hi Stephan,

aber das klingt ja so, als wolltest du ziemlich ausführliche Release-Infos dokumentieren, also immer wenn tatsächlich neue Pakete rauskommen?
Ich hatte nur vor, dass wir die großen Meilensteine v7.1, v7, v6 so dokumentieren…
Und wenn ich du das auch so verstanden hast, dann wäre ja

Version 7.0

Neue Funktionen

  • ziemlich lange Liste

Behobene Probleme

  • das ist schwierig für die 7.0 - es wurden ja zig Probleme behoben, erzeugt, whatever

Besondere Hinweise

  • hier kommt auch die Art von Hinweise hin, um die es gerade geht
  • ebenso Hinweise auf die Migration, usw.
  • immernoch bestehende Probleme

Version 6.2

analog

Ist das, was du gemeint hast?

Wenn wir das so umkrempeln, dann können wir auch gleich überlegen, ob wir überhaupt für die Dokumentation in Zukunft ein großes Dokument behalten und nicht verschiedene Branches… so wie es z.B. python macht „dieses Feature gibt es seit… v7.0“ usw.

VG, Tobias

#11

Für die Doku reicht es denke ich, wenn wir nur die größeren Releases dokumentieren oder wenn Änderungen vorgenommen werden müssen? Ich weiß auch nicht, was der beste Weg ist :slight_smile:

Gedacht hatte ich an so etwas:

Man müsste mal überlegen, wo man die Release-Informationen eigentlich haben will: hier, Github oder in der Doku?

Gute Frage. Ich würde es erstmal so lassen wie es ist. Wenn z.B. Mehrschulfähigkeit dazukommt und es immer noch v7 ist, kann man ja einen entsprechenden Hinweise (seit v7.2 etc.) mit in die Doku als Hinweis schreiben.

#12

Ah, ok. Ich verstehe. Ich habe die Release-Informationen eher als das verstanden, wie wir es auch gemacht haben: eine eher statische Seite, die mehr den Info/Werbezwecken dient als als Datenbank bzw. Liste aktueller Informationen.

Das Problem der Release-Infos ist ja, dass wir mind. 3 wichtige Pakete haben: sophomorix, linuxmuster-base und linuxmuster-webui und der ASK-thread Neue Pakete für lmn7 ist ja dann die (rolling) Release-Info, die ihren Namen verdient. Daher wird der Thread ja auch versucht, sauber zu halten.
Wenn man das in github wollte, müsste man ein zentrales Repo haben, das die anderen einbindet und immer (oder ab und zu) wenn jemand ein sub-repo aktualisiert, gibt es ne neue Version und dann könnte man github releases verwenden.
Insofern, ich will jetzt nicht wirklich in der Doku spiegeln was in dem Thread passiert, wenn das nicht halbwegs automatisiert ginge.

Mein Fazit:
Das bedeutet: bezeichnen wir (solange sich nichts ändert) den Neue-Pakete-Thread als „release infothread“.
Dann könnte man ein screenshot oben ja nehmen. Wenn euch „Release-Informationen“ irgendwie out of place erscheinen, können wir es ja auch „Meilensteine“ nennen.

image

Oder den Vorschlag von toheine übernehmen: so wie oben, nur die „Release-Informationen früherer Versionen“ zurück ins Kapitel „was ist neu?“ und dann bei der Sysadministration ein Kapitel „Bekannte Probleme und Lösungen“

VG, Tobias

#13

Moin!

Blicke gerade nicht mehr durch: Um was geht es den jetzt hier

Bug-Fixes -> Würgdarum

oder Release-Infos?

Können wir den Thread nicht bitte aufräumen?

VG

Thorsten

#14

Zusammenfassung, denn es hängt sehr viel miteinander zusammen

  • Thomas hat ein Paket veröffentlicht mit dem „Obacht!“ Hinweis, dass man etwas manuell tun muss.
  • Ich bin der Meinung das gehört dokumentiert. Ich schlage vor und habe es schon in die offzielle Doku aufgenommen, siehe hier: https://docs.linuxmuster.net/de/latest/about/release-information.html#gefundene-und-behobene-probleme
  • Jetzt ist das aber nicht die geschickteste Stelle. Tobi schlug vor, es nach Systemadministration zu verlagern, Stephan schlug vor, die „Release-Informationen“ neu zu organisieren und zwar so, dass es wie bei anderen Projekten auch ist: zeitlich von neu nach alt, mit Versionsnummern, Fixes und Verweis auf die entsprechenden github commits.
  • Dann bin ich etwas abgeschwifft, weil – wenn schon neu – dann die Release-Infos (wie Stephan sie von anderen Projekten beispielhaft aufgezeigt hatte) am besten in einem Meta-linuxmuster.net github Repo verwaltet würden - aber egal zu weit vom Thema.
  • Fakt ist, dass es so wie es jetzt ist, ok ist, aber nicht schön. Und noch fakter ist es, dass es zeitlich nicht möglich ist ein detailiertes Release-Info-Blog wie im ask in der dokumentation nachzubilden.

Ich merge mal einfach noch meine Änderungen, wo ich das Kapitel „Release-Informationen“ nenne, auch wenn das ein Misnomer ist. Ich hkönnte es auch „Bugfixes“, „Hotfixes“ oder „Errata“ nennen…

VG, Tobias

#15

@toheine,

so ungefähr?
image

die „Release-Informationen früherer Versionen“ würde natürlich nicht dort stehen.
Vg, tobias

#16

@Tobias … das finde ich super!

#17

Hi.

Ich fand die Variante jetzt unter den diskutierten auch den besten Kompromiss.

In folgendem Screenshot seht ihr diesen. Oben nur noch „Was ist neu?“ Das lässt auch zu, dass man mal ein besseres „Release-Information“ herausbringt.
Und dann unter Systemadministration „Fehlerkorrekturen“ (eingedeutscht,…)

image
image916×871 122 KB

wenn ich 2-3 Herzen bekomme, würde ich das so mergen. Es lässt sich aber gerne weiter daran feilen…

VG, Tobias

3 „Gefällt mir“
#18

@Tobias … du bekommst ein Herz … aber mir ist nicht klar warum das dann unter „Was ist neu in 7.0“ steht. Intuitiv würde ich da nicht nach z. B. Fehlerkorrekturen suchen. Ist aber nur ein Gedanke!

#19

hm, das hat sich jetzt so ergeben, weil Stephan zurecht eingewandt hat, dass man ordentliche Release-Informationen so glieder (wie er es oben getan hat) und da gehört „Was ist neu“ genauso dazu, wie Fehlerkorrekturen.
Aber wenn ich „Was ist neu?“ als Kapitelüberschrift nehme - dann hast du recht. Dann erwarte ich keine Fehlerkorrekturen.
Soll ich sie dann gar nicht erwähnen da oben?

Ich frage mich, ob jemand, der ein Problem hat, die Info in der Doku findet. Erwartet jemand, der nach Fehlerkorrekturen sucht, dass die prominent in der Doku zu finden sind, so wie bei „Troubleshooting“? Oder würde der unter „aktuell halten“ und dann weitersuchen?

Hach, schwierig. Ihr dürft gerne noch einen Vorschlag machen, ansonsten lass ich es erstmal so.
VG, Tobias

#20

@Tobias Ich würde deinen Vorschlag jetzt so aufnehmen. Und deine Bemerkung …

… ist ja absolut im Sinne aller Beteiligten!