Sich von seinem Projekt entfernen
lima-city → Forum → Programmiersprachen → Sonstige Programmiersprachen
abstand
anleitung
arbeiten
beispiel
dank
dokumentation
feedback
idee
jemand
leute
menge
nutzen
paar
problem
projekt
server
situation
software
url
wissen
-
Moin Leute,
ich habe ein Problem, wo ich auf anhieb nicht weiter komme. Ich schreibe ein Open Source "Framework", um die NodeJS Server-Entwicklung zu vereinfachen. Es orientiert sich dabei ein wenig an Express, hat aber andere Prinzipien und Konzepte im erweiterten Umfeld. Nun schreibe ich das halt als Hobby, möchte aber, dass nicht nur ich das Nutzen kann, sondern auch andere Entwickler, wie ihr zum Beispiel, davon profitiert. Also möchte ich ein paar Seiten Dokumentation verfassen, welche beschreibt, wie man mit dem Projekt arbeitet, was ich mir dabei gedacht habe, und so ein paar "Best Practise" aufzeigt. So weit so gut, ich habe heute mittag ca. angefangen, und ALLE Ansätze verwerfen müssen, weil ich in ca 3 Sätzen und 2-3 Zeilen Code bereits das "How-To" beschrieben habe, wie man es macht, und fertig. Dass das für mich so einfach ist, das weiß ich, dass das für externe entwickler so einfach ist, bezweifel ich... Nun steh ich irgendwie vor meinem Projekt, und weiß nicht genau, wie ich den nötigen Abstand erreiche, um eine gute und sinnvolle Dokumenation mit How-Tos für externe Entwickler zu schreiben.
Im normalfall ist es für mich kein Problem Abstand zu gewinnen und Dinge zu erklären, aber in diesem Fall bin ich irgendwie.. ich mag fast sagen zu blöd dafür. Darum wolllte ich fragen, wie ihr Abstand von euren Projekten erreicht, um Dokumentationen und Beispiele zu erstellen dafür.
Liebe Grüße
PS: Handelt sich um dieses Projekt: https://github.com/sateffen/nodgine, besonders den develop Branch. -
Diskutiere mit und stelle Fragen: Jetzt kostenlos anmelden!
lima-city: Gratis werbefreier Webspace für deine eigene Homepage
-
Das von dir beschriebene Problem ist umfassend und häufig schaffen es Software Autoren gar nicht, das erklärt warum es eine Menge gute Software gibt mit aus Anwendersicht bescheidenster Dokumentation.
Erschwerend kommt hinzu das man als Autor zunächst mal "nur für sich selbst" arbeitet, die entstehenden lösungen sind dann wie ein Maßanzug, sie passen, aber eben nur für einen selbst, jemand anderes mit ähnlichem Körperbau kann den Anzug ev. tragen aber es wird hier und dort zwicken und zwacken und ein dritter wird ev. nicht mal die Hose zu bekommen
Wie bekommt man also jetzt a) eine bessere allgemeine Passform b) eine brauchbare Dokumentation ?
Eine bessere Passform erhält man dadurch das man das Projekt von Leuten testen lässt die wissen was sie tun ohne das sie am Projekt selbst beteiligt sind, am besten beobachtet man sie beim rumspielen mit der Software und lässt sich von ihnen Feedback geben.
Das ist schwer weil es schwer ist geeignete Probanden zu finden denn der Betatest ist oftmals komplexer als es die eigentliche Softwareentwicklung und man selbst muss viel Arbeit investieren um geeignete Ergebnisse zu erhalten und auch eine ganze Menge Projektleitungskompetenz benötigt was...na ja...nicht die Stärke der meisten Programmierer ist. Außerdem gibt es da eine psychologische Komponente, so ein Betatest führt möglicherweise zu unerwünschtem Feedback, man benötigt die charakterliche Reife damit umgehen zu können und selbst wenn man die besitzt bleibt es eine Herausforderung.
Wenn man jetzt die Ergebnisse des Betatests auswertet dann bekommt man einen Blick für Dinge die man selbst nie beachtet hat, weil man sie gar nicht beachten konnte, weil Andere eben einfach anders arbeiten als man selbst.
Wenn man das auf die Software reflektiert bekommt man eine bessere Software und man bekommt Hinweise auf die Ecken und Kanten die man dokumentieren sollte, vermischt mit Informationen zur generellen Vorgehensweise die zwar für den Autor verständlich ist aber für den Außenstehenden unbedingt zu beschreiben ist und der konstanten Frage: "Was braucht jemand um es benutzen zu können, was muss er wissen ? Entsteht dann eine Dokumentation die man mit möglichst vielfältigen Beispielen, Abbildungen, Diagrammen usw. spicken sollte.
Wenn man dann etwas hat was man für anwendbar hält dann testet man ob es anwendbar ist, man drückt die Anleitung jemandem in die hand der das (in der Anleitung aufgeführte) nötige Vorwissen besitzt um die Anleitung (und die Softweare) zu verstehen und bittet Ihn die anleitung umzusetzen, auch hier benötigt bes idealerweise Beobachtung und natürlich Feedback, auch das reflektiert man wieder auf die Software und die Anleitung zurück.
So erhält man Schritt für Schritt eine gute Software und eine passende Doku.
-
Danke für die Antwort fatfox
Ja, das erstellen von guter Software ist ein iterativer Prozess. Ein "Alphatest", oder auch Beta, einfach ein Test von deren wollte ich initieren, wenn die Version 0.2 fertig ist. Vorher fehlen noch ein paar Ideen, die das Projekt eigentlich erst wirklich nutzbar macht. Im develop Branch ists zwar schon großteils umgesetzt, aber das ist alles noch in der Entwicklung.
Ich denke, ich werd schauen, eine Dokumenation so gut wie möglich hinzukriegen, und dann, wie du sagst, nach und nach perfektionieren. Direkt von Anfang kann es nicht perfekt werden, leider :-S
Übrigens: Ich habe des Framework mit absicht so gehalten, dass es theoretisch weite Einsatzgebiete haben kann. Am anfang war es eigentlich nur ein NodeJS Server Konstrukt, welches Sensoren abstrahiert und deren Daten aquiriert, und die Werte dann persistiert und für andere Applikationen verwertbar weiterverarbeitet. Weil mir aber Express zb nicht gepasst hat, und auch andere bestehende Frameworks irgendwie bescheiden waren, für das wie ich es wollte, hab ich mein eigenes Grundsystem geschrieben. Imo wirds von mir persönlich und von einer Firma verwendet, und das bisherige Feedback der Entwickler in der Firma ist sehr gut (leider). Ich hoffe, dass des Review von mehr externen Entwicklern auch ein paar Ideen einbringt, die mir noch nicht gekommen sind.
Ich setz mich mal ran, und bau mir nen kleines Diagramm, wie ich glaube, dass eine Doku geeignet wäre, und dann schreib ich was, das hoffendlich hilft.
Danke, liebe Grüße und frohe Ostern -
Meine Sicht der Dinge:
Dokumentation muss auf mehrenen Ebenen existieren bzw. für verschiedene Situationen geschrieben werden.
Situation "Erster Eindruck": Beschreibe worum es bei deinem Framework geht. Welche Probleme es löst. Was dich dazu gebracht hat es zu schreiben. Vergleiche es mit bestehenden Frameworks und einer NodeJS-Anwendung ohne dein Framework. Diese Art von Dokumentation kann auch in Form eines FAQs gestaltet werden. Stelle dabei sicher, dass deine Leser genau verstehen womit sie es hier zu tun haben und wofür sie es nutzen können.
Situation "Verständnis der Architektur": Dein Framework basiert wahrscheinlich auf mehreren großen Ideen. Diese Ideen solltest du erklären und ihre Vorzüge aber auch ihre Nachteile beschreiben. Versuche zu erklären, wie mehrere deiner Ideen zusammenwirken, damit der Nutzer deines Frameworks ein Gesamtbild bekommt und auch versteht, wie er das Framework einsetzen sollte.
Situation "Erfahrung sammeln": Hier solltest du einige Tutorials für typische Anwendungen schreiben. Dabei sollten wichtige und zentrale Features hervorgehoben werden, damit der Benutzer die theoretischen Aspekte der Architektur auch noch einmal von der praktischen Seite betrachten kann. Das Howto, das du schon angefangen hast, passt in diese Situation.
Situation "Fortgeschrittene Anwendung schreiben": Diese Dokumentation bezieht sich wahrscheinlich auf die API deines Frameworks. Idealerweise sollte es zu jeder Funktion ein kleines Beispiel geben und die API selbst sollte gut sortiert sein, so dass man schnell findet, was man sucht. Hier geht es wirklich um die Details, die man nur dann nachschlägt, wenn man sie wirklich wissen muss.
ergänzendes edit: Was ich auch sehr nett finde, aber was man leider nur selten geboten bekommt: Die Möglichkeit die Doku komplett und unkompliziert runterzuladen. Dann kann man auch ohne Internetverbindung an seinen Projekten arbeiten.
Beitrag zuletzt geändert: 21.4.2014 13:27:04 von bladehunter -
Danke für das weitere Feedback. Das ist eine gute Untergliederung. Ich habe mir den Thread als Bookmark gespeichert, um eure guten Tipps nicht zu verlegen.
Ich habe mir jetzt mal eine grobe Struktur angelegt (nicht vollständig), welche Einträge ich auf jedenfall schreiben muss. https://github.com/sateffen/nodgine/wiki. Ich hoffe, dass damit dann das Testen mit Version 0.2 so ablaufen kann, dass ich da dann Input kriege, um das weiter anzupassen.
Allgemein, alles in Englisch, auch wenn mein Englisch nicht das beste ist, aber ich kann es nur lernen, wenn ich es versuche aktiv zu nutzen, also auch zu schreiben. Wenn ihr mal rüberschaut, und was findet, was fehlerhaft ist, sagt mir bitte unbedingt bescheid. PN, Gästebuch, auch nen Github-Issue, jenachdem, was ihr bevorzugt. Nur an Fehlern kann ich wachsen, und die find ich nur schwer selbst :-S
Vielen Dank und liebe Grüße -
Diskutiere mit und stelle Fragen: Jetzt kostenlos anmelden!
lima-city: Gratis werbefreier Webspace für deine eigene Homepage
