Ich habe nun angefangen mein Projekt zu dokumentieren, bzw. habe es teilweise noch vor.
Was mir Kopfschmerzen bereitet ist die User und Developer Manual.
Ich hab mich ein bisschen im Netz umgeschaut und mir die User Manual von Unreal Engine, jmonkey, ogre und noch ein paar angeguckt und die sind alle samt nicht so gut, als dass diese manuals mir den Einstieg bzw. genug Informationen bieten um los zu legen. Daher hab ich bisher keine gute Vorlage an der ich mich Orientieren kann.
Theoretisch kann man viel machen, es gibt auch hier und da mal 1-2 Tips wie man sowas macht aber Theorie und Praxis liegen so weit auseinander.
Was ich nun also suche sind gute Manuals für User und/oder für Developer bzw. Artikel wie man für solche vorgehen sollte.
Ich möchte vermeiden, Wochen zu investieren, um dann etwas zu haben, was unbrauchbar ist, weil es am ziel völlig vorbei ist, da ich keine Erfahrung in sowas habe und ich das System Entwickelt hab und damit ne völlig andere Perspektive davon hab.

Ich denke ich bin nicht der einzige mit dem Problem, daher hoffe ich hier eine Diskussion entstehen zu lassen, die Hilfreich ist.

_________________
"Wer die Freiheit aufgibt um Sicherheit zu gewinnen, der wird am Ende beides verlieren"
Benjamin Franklin

Projekte: https://github.com/tak2004

"Ich hab mir die Doku verschiedenener bestehender Projekte angesehen und fand keine" <- willkommen im Leben

Mal ernsthaft, gute Doku zu schreiben ist eine Kunst und etwas, was viele nicht können (obwohl sie denken, dass sie es tun). Weder mit automatisch generierten UML-Diagrammen, noch mit automatisch (oder halbautomatisch) generierter API-Dok oder sonstiger Massenware ist es getan.

Erfahrungsgemäß hilft vor allem ein architektureller Überblick dem User weiter. Also etwas, das ihm erklärt, wie das System so prinzipiell funktioniert, welcher Teil was übernimmt, warum der entstand, ..., will heißen: Das Konzept dahinter.

Wenn der User das mal begriffen hat, kommt er IMHO mit UserGuides erstmal am weitesten. Die können aus kleinen, einfachen (u.U. erklärten) Codebeispielen bestehen, sollten aber die gängisten Fragen abdecken. Quasi ne bessere FAQ, die aus zusammenhängenden Fragen besteht.

Als Beispiel sei da mal der UserGuide von specs und sbt zu nennen. Der von specs deckt die gängisten (in den anderen Artikeln sogar alle) Verwendungsmöglichkeiten von specs ab, zeigt wie man wie welchen Unit-Test bastelt... und der sbt-Guide zeigt, wo man den Classpath setzt, wo man Libraries angibt, die zum Build benötigt werden, wie man eigene Tasks baut, usw.

Der Userguide geht also stückweise auf das ein, was den User definitiv interessieren wird.

Wenn du das hast, sprechende Namen für deine Klassen, Methoden und Parameter verwendest und vllt. noch ein, zwei Klassendiagramma hast, dann hast du gewonnen.
Wichtig ist dann nur, dass du den Spaß aktuell hältst. Spätestens daran scheitern viele

Klappt es aber, dann hat der User das Konzept hinter deinem Framework durchstiegen, wurde an die Hand genommen und kam so schnell zu ersten Erfolgen und hat dank deiner gut designten API die Möglichkeit, sich weiter einzuarbeiten, wenn er das möchte.

Hier mal ein paar Links zu IMHO gut gemachter Doku:

• Specs Quickstart
• Specs Userguide
• Die SBT Dokumentation

Die haben alle ein mehr oder weniger kleines Setup am Anfang, dann einen quick-n-dirty way, wie man schnell erste Sachen macht und dann ausführliche, konzeptlastige Erklärungen.

Hope this helps,
~ Frase

_________________
"Für kein Tier wird so viel gearbeitet wie für die Katz'."

Ich würde das so ähnlich sehen. Wenn ich auf Arbeit in ein neues Projekt komme, dann brauch ich immer ewig mich da zurecht zu finden. Was mir helfen würde wäre:

1. ein einsteiger Tutorial für die verschiedenen Entwicklungsaufgaben die Anfallen
2. eine Architekturübersicht
3. eine Komponentenübersicht
4. eine Datenmodellübersicht.

Das Problem bei unseren Projekten ist, dass die recht flüssig sind und sehhhr groß d.h. selbst wenn die Übersichten da sind sind sie unübersichtlich.

Aber mit den 3 Übersichten und 3-4 Tutorials, solltest du schon recht viel bieten können.

_________________
Blog: kevin-fleischer.de und fbaingermany.com

Ich hab meine Doku in 3 Teile eingeteilt.
http://www.radonframework.org/projects/ ... umentation
-Code Doku
-User Manual
-Developer Manual

Die User Manaual hab ich nun auch in 3 Teile geteilt.
-Getting started
-Tutorials
-Tech Talk

Alles an Hintergrund Wissen kommt in Tech Talk, Tutorials sollen auf dem Quellcode basieren und Getting started ist das setup und ein schnell einstieg.

Die Developer Manual soll dann die Erstellung von Modulen, Plugins und infos zum ändern des Codes bieten.

Soweit erstmal mein Plan.
Irgendwelche Ideen, Hinweise, Verbesserungsvorschläge oder kann man die Aufgliederung als solches stehen lassen ?

_________________
"Wer die Freiheit aufgibt um Sicherheit zu gewinnen, der wird am Ende beides verlieren"
Benjamin Franklin

Projekte: https://github.com/tak2004