Seite 1 von 1

GitHub für Dokumentation nutzen?

Verfasst: Fr 17. Apr 2015, 18:37
von Tony Ford
Hallo liebe OSEG-Gemeinde

Diese Woche habe ich gemeinsam mit Florian Rabis in Dresden über OSEG gesprochen und wie haben verschiedene Ideen diskutiert. Florian brachte hierbei das Thema Dokumentation ins Spiel, welche bei OSEG bislang nicht systematisch durchgeführt wird, sondern sich auf verschiedenste Quellen verteilt.

Dies erschwert es für andere Entwickler, an einem solchen Projekt selbst entwickeln, probieren, testen, usw. zu können.

Die Dokumentation einheitlich zu machen scheiterte bislang vor allem an dem Problem der Doppelpflege und Verteilung auf mehrerer Lokalitäten.
Einem Entwickler ist es nur schwer zu vermitteln, neben seiner bislang gewohnten Dokumentationsplattform noch andere Plattformen aufsuchen und diese pflegen zu müssen. Kommt noch hinzu, dass es zu einem Projekt unter Umständen zwei verschiedene Informationen gibt, was natürlich vermieden werden sollte.

Doch da kam mir GitHub in den Sinn. Seit wenigen Wochen nutze ich GitHub aktiv um selbst IT-Projekte zu verwalten und zu dokumentieren und finde, dass GitHub zur Dokumentation und Hinterlegung z.B. fertiger Konstruktionen, Baupläne, Beschreibungen, Zusammenfassungen von Testläufen, usw. sehr gut geeignet wäre.

Ein anderer Entwickler, welcher Interesse am Projekt hat und selbst z.B. mal daran arbeiten möchte, der kann sich dieses Projekt mit "git clone ..." auf seinem PC kopieren und hat dann alle notwendigen Daten zur Hand um sofort loslegen zu können.

Will er eigene Entwicklungen dokumentieren, so kann er ggf. Forks generieren.
Will er bestehende Entwicklungen weitere Dinge hinzufügen oder optimieren, so kann er dies an den Master des Projektes senden, welcher dann diese neuen Daten in sein Projekt einfließen lassen kann.

All dies kann er von seinem PC aus tun und muss keine weitere Seite oder Plattform aufsuchen.

Weiteres Potenzial sehe ich in der Kombination mehrerer Komponenten. D.h. wenn Jemand z.B. eine PV-Anlage entwickelt, so bindet der sogenannte Submodule "Batteriemanagement" "Akku" "Netzumschaltung" "PV-Modul" usw. ein und kann darüber komplexe Gebilde aufbauen.
Der Vorteil dabei ist, dass diese Gebilde "lebendig" sind, d.h. die Entwicklung in den Submodulen durch andere Entwickler weitergeht, sich der Entwickler der PV-Anlage nicht weiter kümmern muss, außer die Rahmenbedingungen im Auge zu behalten und ggf. Submodule entsprechend in ihrer Skalierung definieren, usw.

Damit keine Missverständnisse aufkommen, es geht mir um die Dokumentation abgeschlossener Teile / Projektabschnitte.
D.h. die Dokumentation während der Entwicklung bleibt jedem überlassen, doch wenn z.B. ein Bauteil fertig konstruiert, eine Testreihe abgeschlossen, ein Bauplan fertig gezeichnet, ein Projektabschnitt abgeschlossen wurde, so wäre eine Dokumentation in GitHub (Ordner kann lokal vom PC aus erstellt und bearbeitet werden) sinnvoll.
Am besten man stellt sich als Entwickler die Frage "Kann ein anderer Entwickler an der genannten Stelle mit den Daten sinnvoll weiterarbeiten?" Wenn man dies mit Nein beantworten muss, weil die ganze Sache noch zu experimentell und ungeordnet ist, dann ergibt auch ein Update in GitHub keinen Sinn.
Wenn man die Frage mit Ja beantworten kann, d.h. man einen Stand erreicht hat, von dem aus andere Entwickler weitermachen könnten, so ergibt es durchaus Sinn, es in GitHub zu dokumentieren bzw. die entsprechenden Daten hochzuladen.

Da nicht Jeder mit GitHub vertraut ist, ich zugegebenermaßen auch noch Anfänger bin, so sei jedoch gesagt, ist GitHub relativ leicht zu erlernen und würde ich mich gern darum bemühen, eine Art kurze Einführung zu geben und Fragen zu beantworten.

Was haltet ihr von dieser Idee?

TF

Re: GitHub für Dokumentation nutzen?

Verfasst: Mo 20. Apr 2015, 17:19
von case
Hi Sebastian,


tjaa, da spricht im Grunde nix gegen ... weshalb ich das auch schon gemacht habe ;) siehe

http://wiki.opensourceecology.de/ZACmeter#Software


Bezüglich der von Dir beschriebenen Kriterien, ab wann man etwas nach Git hochladen sollte, möchte ich noch folgendes hinzufügen bzw. hervorheben:

GIT ist ein Versions-Kontroll-System. Bevor es Git gab wurde meist CVS (Concurrent Versions System) eingesetzt, welches vor allem wichtig war, um Versionen von verschiedenen Entwicklern zu pflegen und Teile davon in die Hauptversion (Master-Branch) einfliessen lassen zu können. D.h., ein System wie Git sollte spätestens dann zum Einsatz kommen, wenn mehrere Entwickler an einem Projekt arbeiten, was bei uns ja bislang eher nicht gegeben ist.

Aber natürlich kann man auch schon vorher die Ressourcen eine Projekts nach Git hochladen. Ich selbst würde wahrscheinlich damit anfangen, sobald es von einem Projekt oder einer Projekt-Ressource mehrere Folge-Versionen gibt bzw. sobald eine davon halbwegs brauchbar ist und als "stable" erachtet werden kann. Vorher ist wahrscheinlich noch zuviel Entwicklungsdynamik, d.h., das Ding ist noch experimentell.

Wie gesagt, bislang haben wir noch nicht dieses Reifestadium bei unseren Projekten, aber ich schätze mal, sobald das der Fall ist und erst recht wenn mehrere Leute dran arbeiten, dann wird es wohl ohnehin selbstverständlich sein, Git zur Versionskontrolle zu nutzen.

Gruss, Oliver

Re: GitHub für Dokumentation nutzen?

Verfasst: Di 21. Apr 2015, 22:35
von Tony Ford
Hallo Oliver

so wie du es beschrieben hast, habe ich es mir auch gedacht. Es ergibt sicherlich wenig Sinn, ein Projekt im experimentellen Stadium darin zu veröffentlichen.