Move wiki to something better for documentation

[caco3]

I am not really getting warm with the wiki as we have it now.

Its its basically a punch of loosely linked pages without a structure.

Should we consider to move to something else eg. like https://readthedocs.org/
And properly rewrite it with a structure?

@jomjol @haverland @Slider0007 and others, what do you think?

[jomjol]

I don't know readthedocs.org. How much effort is it to tranfer it? I don't have too much time, to do so.
I would look different, if we could make a busness out of this high effort.

[caco3]

I also would want to make the effort as minimal as possible.

Looking at https://medium.com/medialesson/documentation-in-github-pages-with-mkdocs-readthedocs-theme-920b283215d1 it seems mkdocs would fit better as we simply could copy the wiki pages to markdown files.

This is the example link from the mentioned blog: https://wp-net.github.io/WordPressPCL/

I like the navigation on the sidebar and also the search functionality.
Both things I strongly miss in the wiki.
We could publish is on the github pages which we already use.
I just will need to find a way to combine it with the github page actions which we already use.

let me play a bit and show you what we could do.

[caco3]

I made a proof-of-concept, see https://caco3.github.io/AI-on-the-edge-device/

For this I simply setup the mdocs and the needed actions for the deployment.
Then I copied all wiki pages into a subfolder without further work on them.

@jomjol What do you think?

It will need some cleanup, eg. updating the internal links, but in general it works without much hassle.

[jomjol]

I like this idea and if it is that easy, let's go for it!

[caco3]

Dann gibt es mehrere Varianten, wie wir es machen können:

1. Die Doku als Ordner in rolling
2. Die Doku in einem separaten branch
3. Die Doku in einem separaten Repo

Mein Eindruck:

1. Würde ich nicht machen, da wir dan ganz viele commits in rolling haben und es für ein Release unübersichtlich wird.
2. Würde ich auch nicht machen, da die Gefahr besteht, dass jemand aus Versehen in den falschen Branch commited. Ausserdem ist es von der Git History komisch, einen Branch zu haben, der nie in master/rolling gemerged werden darf.
3. Diese Lösung wäre für uns wohl am Sinnvollsten. Da können wir völlig unabhängig und ohne den Anspruch auf schön dokumentiere PR an der Doku arbeiten. Homeassistant macht es übrigens auch genau so: https://github.com/home-assistant/home-assistant.io

Für die letzte Varianet wäre es am besten, wenn Du ein neue Repo anlegst, z.b. AI-on-the-edge-device-Docs. Und die gleichen Leute wieder als Colaborateur einsetzt. Und setze die github-pages auf den branch gh-pages, das ist am einfachsten in dem Fall.

---

Du solltest Dir auch mal überlegen, ob es ok wäre, das Projekt von einem Privaten Konto in eine Organisazion (GitHub Free für Organsationen) zu ändern. Dann müsstest nicht Du immer alle Github-Einstellungen verwalten.
Die Unterschiede sind hier aufgeführt:

• https://docs.github.com/de/get-started/learning-about-github/types-of-github-accounts
• https://docs.github.com/de/get-started/learning-about-github/githubs-products#github-free-f%C3%BCr-organsationen

Und ich habe gesehen, dass wir mit unseren Github Actions aufpassen müssen. Wir haben 2.000 GitHub Actions-Minuten pro Monat gratis zur Verfügung. Ein Build dauert ca. 10 Minuten, somit können wir nur 200 Builds pro Monat machen. Ich denke, momentan verbrauchen wir ein mehrfaches (Ev. kannst Du das irgendwo nachschauen), da wir jeden commit bauen. Schonender wäre es, nur bei Bedarf oder einem PR zu bauen.

[haverland]

Dann gibt es mehrere Varianten, wie wir es machen können:

1. Die Doku als Ordner in rolling
2. Die Doku in einem separaten branch
3. Die Doku in einem separaten Repo

Mein Eindruck:

1. Würde ich nicht machen, da wir dan ganz viele commits in rolling haben und es für ein Release unübersichtlich wird.
2. Würde ich auch nicht machen, da die Gefahr besteht, dass jemand aus Versehen in den falschen Branch commited. Ausserdem ist es von der Git History komisch, einen Branch zu haben, der nie in master/rolling gemerged werden darf.
3. Diese Lösung wäre für uns wohl am Sinnvollsten. Da können wir völlig unabhängig und ohne den Anspruch auf schön dokumentiere PR an der Doku arbeiten. Homeassistant macht es übrigens auch genau so: https://github.com/home-assistant/home-assistant.io

Ich wäre auch für Option 3). Da wir gerade bei Doku eher weniger 4-Augen-Prinzip machen, ist das glaube die beste Option.

[jomjol]

Gute Punkte - schaue ich mir nächstes Jahr an.
Guten Rutsch!

[caco3]

danke, dir auch

[caco3]

So wie ich https://docs.github.com/de/billing/managing-billing-for-github-actions/about-billing-for-github-actions verstehe, haben wir keine Limite, da wir öffentliche Repos haben:

Die Nutzung von GitHub Actions ist für GitHub-gehostete Standardrunner in öffentlichen Repositorys und für selbstgehostete Runner kostenlos. Für private Repositorys erhält jedes GitHub-Konto eine bestimmte Menge an Freiminuten und kostenlosem Speicherplatz für die Nutzung mit GitHub-gehosteten Runnern

Somit müssen wir keine Angst wegen Kosten für die Autobuilds haben. Dennoch habe ich die Builds durch Caching beschleunigt (#1737)

[caco3]

Ich habe mich ein bisschen in einen möglichen Transfer von privaten Repos (z.Z. bereitgestellt von @jomjol) zu einer Organisation befasst..

Eine Organisation hätte den Vorteil, dass nicht nur @jomjol die Einstellungen anpassen kann (das kann beim Privaten Repo nur der Owner, nicht aber die Colaborateurs). Zudem könnten wir alle Repos, welche Bezug zum Projekt haben, zusammenfassen. Soviel ich sehe, liegt. z.Z. auch einiges bei @haverland.

@jomjol würde damit aber auch ein bisschen den Lead abgeben, deshalb will ich die Entscheidung ihm überlassen!

Dann gibt es offenbar mehrere Möglichkeiten für eine Migration:

1. Beibehalten des persönlichen Kontos und manuelles Erstellen einer neuen Organisation. Und dann alle repos transferieren
   (Siehe https://docs.github.com/de/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/converting-a-user-into-an-organization#keep-your-personal-account-and-create-a-new-organization-manually)
   Soweit ich sehe, würden auch die Issues transferiert, was mir wichtig scheint.
   Diskussionen können zumindest einzeln verschoben werden. Ob/Wie das auch für alle zusammen geht, konnte ich nicht herausfinden :(
2. Das persönliche Konto automatisch in eine Organisation umwandeln (Siehe https://docs.github.com/de/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/converting-a-user-into-an-organization#convert-your-personal-account-into-an-organization-automatically). Das würde alle Repos von @jomjol transferieren, was sicher nicht sinnvoll ist!

[caco3]

Nachtrag:

Ich habe Testweise eine Organization erstellt und dann mein Fork dahin transferiert. Zuvor habe ich zum testen einige Issues and Diskussionen erstellt.

Es wurden alle Issues und Diskussionen korrekt transferiert, sollte also alles ohne Probleme gehen: https://github.com/caco3-test-org/AI-on-the-edge-device

Bestehende Links werden automatisch umgeleitet, Beispiel: caco3#10

Beispiele von grösseren organisationen:

• https://github.com/home-assistant
• https://github.com/nextcloud

[haverland]

Eine Organisation hätte den Vorteil, dass nicht nur @jomjol die Einstellungen anpassen kann (das kann beim Privaten Repo nur der Owner, nicht aber die Colaborateurs). Zudem könnten wir alle Repos, welche Bezug zum Projekt haben, zusammenfassen. Soviel ich sehe, liegt. z.Z. auch einiges bei @haverland.

Ja, link auf meinen Fork war keine gute Idee. Ich hatte gestern schon das Testing-Wiki nachgetragen, da ich gerne mal meinen Fork lösche, nachdem ich Release-Tests im master gemacht habe.

Wenn ihr noch einen Link auf meinen Fork findet, gerne posten. Ich versuche dann den nachzutragen.

[caco3]

Ich bin schon mal ein bischen am herumspielen mit der mkdocs config.
Wenn wir dann migrieren, müssen wir das wiki einfrieren und die Dateien minimal anpassen. Für den ersten wurf können wir sie aber 1:1 übernehmen.

Beispiel config: https://caco3-test-org.github.io/AI-on-the-edge-device/
Habe bis jetzt vor allem mit der Sidebar links gespielt.

[Slider0007]

@caco3 : Das schaut doch richtig gut und modern aus.

[jomjol]

@caco3 @haverland
Folgende Überlegungen meinerseits:

Eigene Orga

• Finde ich übertrieben, weil das auch eine Erwartungshaltung weckt, die wir nicht erfüllen würden.
• Langfristig sehe ich auch keine riesen Sprünge in der Software. Denn die müssten wir auch maintainen und da sehe ich Kapalimits, da wir das alles in der Freizeit machen
• Ich will auch nicht die komplette Kontrolle aus der Hand geben, da einige parallel Projekte darauf basieren.
• Fazit: ich würde gerne in der aktuellen Orga bleiben

Dokumentation

• Umzug auf eine professionellere Version finde ich gut.
• https://caco3-test-org.github.io/AI-on-the-edge-device/ gefällt mir sehr.
• Was konkret muss getan werden?

[haverland]

Optisch macht die Seite schon wesentlich mehr her. Mir fällt auch auf, dass viele User die Wiki-Einträge nicht finden/sehen.
Deine Frage nach der Pflege ist schon berechtigt. Ich habe was Oberflächen angeht zwei linke Hände. Content liefere ich gerne.

Konkret ist das ganze wohl kostenlos - auch für öffentlich private Github-Accounts. Insofern sehe ich da auch nicht die Notwendigkeit das als Organisation aufzuziehen.

Wie @caco3 das gezaubert hat, erklärt sich mir aber auch nicht.

[caco3]

@jomjol Danke für dein Statement, dann lassen wir das so wie es ist.

Kannst Du uns bitte:

• Ein Repo erstellen, z.B. AI-on-the-edge-device-docs
• Uns als Collaborateur hinzufügen
• Einen Branch gh-pages erstellen
• In den Settings die Github pages auf diesen branch setzen

Dann kann ich das Wiki darauf umziehen.

Wie @caco3 das gezaubert hat, erklärt sich mir aber auch nicht.

Das war echt nicht viel, da ich die Wiki pages 1:1 übernehmen konnte. Gerne zeige ich euch dann, wie es funktioniert.

Ich habe was Oberflächen angeht zwei linke Hände. Content liefere ich gerne.

Bei mir ist es genau umgekehrt, somit können wir uns super ergänzen.

[jomjol]

Kannst Du uns bitte:

* Ein Repo erstellen, z.B. `AI-on-the-edge-device-docs`

Done: https://github.com/jomjol/AI-on-the-edge-device-docs

* Uns als Collaborateur hinzufügen

Done

* Einen Branch `gh-pages` erstellen

Done

* In den Settings die Github pages auf diesen branch setzen

War schon so:

Hoffe das passt so!

@caco3 : super Dank für deinen Einsatz für die Optik und Übersichtlichkeit. Ich bin auch eher wie @haverland begabt :-)

[caco3]

Danke @jomjol

Ich habe es soweit migriert und auf jeder Wiki-Seite eine Notiz angehängt.

https://jomjol.github.io/AI-on-the-edge-device-docs/

Da hat es auch ein readme, welches versucht zu erklären, ansonsten bitte einfach fragen.

Gerne könnt Ihr bereits jetzt schon durch die Seiten gehen und sie überarbeiten.

Auch im readme hier und in der firmware sollten wir später dann auch alle links aktualisieren

[jomjol]

Mega cool - vor allem die Automatisierung.

Im ersten Schritt würde ich das Wiki hier komplet löschen und nur eine Seite mit Verweis auf die neue Doku geben.

Passt das soweit oder habe ich etwas übersehen?

P.S.: den Hinweis auf der ersten Seite habe ich gesehen, aber ich meinte, dass wir jetzt ALLES im Wiki hier löschen.

[caco3]

ich würde die Wiki Inhalte erst löschen, wen wir mehrheitlich migriert haben, ich will da mal zuerst alle Seiten überfliegen.
Und die Wiki Seiten selber würde ich erst später löschen, wir haben vom readme und der firmware (Web UI und log) noch referenzen ins wiki, die sollten wir zuerst aktualisieren.

[caco3]

So, ich habe jetzt mal alle Seiten in die Navigation einsortiert und grob revidiert.
Es gibt aber noch viel zu überarbeiten. Viele Seiten sind nicht mehr aktuell.

Nehmt euch doch ein paar Seiten an und aktualisiert sie!

Das Wiki habe ich geleert, die Pages aber noch belassen, da wir links drauf haben.

[jomjol]

Ich habe heute Nachmittag mal angefangen, den Initialen Setup-Modus zu beschreiben.