search

bundesAPI / sofortmassnahmen

Zivilgesellschaftliche Beteiligung zu den „Sofortmaßnahmen Zweites Open Data Gesetz“
96 stars 3 forks source link

Dokumentation des Projekts #55

Open DevertNet opened 2 years ago

DevertNet commented 2 years ago

Hallo zusammen,

über Umwege bin ich auf dieses Projekt gestoßen und hätte Lust es etwas zu Unterstützen :)

Beim durchstöbern und durchdringen des ganzen Umfangs ist mir eins aufgefallen: Es gibt keinen roten Faden in der Gesamtdokumentation. D.h. man ist etwas Verloren, wenn man sich einem Überblick verschaffen möchte. Manche Dinge scheinen auch etwas vermischt und ich hab mir oft die Frage gestellt: Was ist das hier nun genau?

Hier sehe ich Optimierungspotenzial und würde das ggf. selber in Angriff nehmen.

Folgende Themen sehe ich:

  1. Es sollte ein Haupt-Repo geben das als Einstiegspunkt dient, in dem das Projekt Dokumentiert ist. Z.B. Worum geht es? Was sind die Ziele? Wie kann ich Unterstützen? Wo ist was? Anbieten würde sich dafür https://github.com/bundesAPI/apis alternativ könnte man aber auch ein eigenes Repo erstellen.
  2. Dokumentation wie die Python Clients generiert werden
  3. README für dieses Repo erstellen: https://github.com/bundesAPI/apis falls es nicht der Einstieg wird.
  4. README erweitern, falls das Repo noch aktuell ist https://github.com/bundesAPI/openapi-status-check
  5. Repo Umbennen und README erweitern: https://github.com/bundesAPI/landing
  6. Issues aus https://github.com/bundesAPI/sofortmassnahmen gehören eig. eher in ein anderes Repo, da es dort ja eher um die Ausarbeitung des Vorschlags geht?
  7. Wurde schon mal diskutiert ob die Dokumentationen in deutsch oder englisch verfasst werden sollen? Die APIs sind sicherlich auch für andere Personen in z.B. Europa interessant, die auf deutsche Daten zugreifen wollen.

Bevor ich mich nun aber fröhlich ans Werk mache, würde ich vorher gerne wissen ob die Änderungen grundsätzlich gewünscht sind oder ob bereits eine andere Struktur in Planung ist?

wirthual commented 2 years ago

Hi @DevertNet, Danke dir fuer die guten Ideen. Ich stimme dir zu, an der Dokumentation gibt es noch verbesserungspotenzial. Umso mehr freut es uns das du dir schon einmal gute Gedanked dazu gemacht hast.

So weit ich weis ist noch keine Neu-Organisation in Planung. Gerne kannst du im Bund.dev Slack channel einmal nachfragen und evtl. mehr input bekommen ueber deine geplante Struktur.

Evtl. kann auch @lukaspanni etwas dazu sagen, der hat sich auch schonmal mit der Dokumentation beschaeftigt.

lukaspanni commented 2 years ago

Ich habe mich vor allem mit autogenerierter Dokumentation für die api Clients beschäftigt. Da ist bereits einiges passiert (siehe repo api-doc-template). In letzter Zeit hat sich allerdings leider kaum etwas getan.

Was unbedingt notwendig ist, ist eine ansprechende Dokumentation innerhalb der repositories und eine Dokumentation der generellen Projektstruktur. Ich bin gerne bereit @DevertNet zu unterstützen. Ich würde vorschlagen, mit einem Überblick über die gesamte Struktur und die Bedeutung der einzelnen repos zu beginnen. @LilithWittmann wird die Gesamtstruktur am besten überblicken.

AndreasFischer1985 commented 2 years ago

Ich habe die README.md in https://github.com/bundesAPI/.github/tree/main/profile mal etwas ergänzt, sodass https://github.com/bundesAPI nun einen besseren Einstiegspunkt in unsere Aktivitäten bieten sollte. Für einen Überblick zur generellen Projektstruktur scheint mir das der beste Ort.

Das apis-repo eignet sich nur bedingt als Einstiegspunkt, weil das mit README.md erstmal nicht mehr auf bund.dev/apis angezeigt wird (sondern auf apis.bund.dev).

septatrix commented 2 years ago

Es wäre sehr schon, wenn klar gekennzeichnet ist wie die jeweiligen APIs konsumiert werden dürfen (private Nutzung, kommerziellen Nutzung, etc)