Forum

Es ist ja bereits viel geschrieben und nachgedacht worden.

Da ja auch viel Zeit vergangen ist, können sich die Ansichten ja auch geändert haben. Daher möchte ich das Thema gerne noch mal aufgreifen.

Wie sollte eine Dokumentation aufgebaut sein.

Sollte es einen Teil geben der eine Erstinstallation beschreibt? Wie ausführlich? Stichwort Server/Rechte Einstellungen)

Dann jedes Modul für sich? Aufgaben bezogen? Mehr Bilder? Mehr Text?

stefan schrieb am 12.09.2007 um 07:52:21 Uhr folgendes:

Wie sollte eine Dokumentation aufgebaut sein.
Sollte es einen Teil geben der eine Erstinstallation beschreibt? Wie ausführlich? Stichwort Server/Rechte Einstellungen)
Dann jedes Modul für sich? Aufgaben bezogen? Mehr Bilder? Mehr Text?

Es sollte drei Arten von Dokumentation geben (oder drei Teile in Einer)
1. ein LEITFADEN (HowTo) der sich vor allem an Beginner (ich möchte nicht von Anfängern sprechen) richtet, worin der "an die Hand genommen wird". Das fängt an bei Entscheidungen, die man vorher treffen muß (welche Datenbank, welches Betriebssystem, ... dazu Entscheidungshilfe: Vorteile/Nachteile ), geht über die Installation, die wichtigsten (häufigsten) Probleme bei der Installation und Einrichtung, über die Grundeinrichtung (was muß ich anpassen, was kann erstmal so bleiben) bis hin zu einer ersten website, die die wichtigsten (häufigsten) Funktionalitäten enthält (Begrüßungs-/Einstiegsseite, Über uns, irgendein Thema, Impressum, Kontakt, Links, sitemap, ...). Wenn man dann als Neuling DORT angekommen ist, hat man die richtige Motivation, um sich "durch den Rest zu qualen".
2. ein LEXIKON, also wo ich, alphabetisch oder thematisch geordnet, was NACHSCHLAGEN kann. Dort würde man z.B. die Beschreibung der einzelnen Module finden. Dies richtet sich an die ANWENDER, die mehr oder weniger täglich damit zu tun haben - und "wie ging das nochmal" oder "wie geht das" brauchen - und keine Grundlegenden Erläuterungen mehr.
3. eine TECHNISCHE Dokumentation, die die System-, Installations-, und sonstige Vorraussetzungen beschreibt, Code-Schnippsel zum "Abkupfern" enthält (man muß nicht jedesmal was neu erfinden), Hinweise zum Geschwindigkeit-Tuning, Datenbank-Geschichten (z.B. technische Unterschiede), webServer(Apache)-Einstellungen, php-Einstellungen, vielleicht Unterschiede der Installation bei verschiedenen Linux-Distributionen (wie heißen die Pakete, die benötigt werden und wo finde ich die). Auch auf die Rechtliche Seite (z.B. Lizenzpflicht für MySQL in gewerblicher Anwendung) sollte aufgeführt sein.

Zur Frage "mehr Bilder" kann man nur sagen: Ein Bild sagt mehr wie tausend Worte - muß ja nicht gleich Focus/BildZeitung-Niveau erreichen. Da wo es die Erklärung VEREINFACHT und VERKÜRZT sind Screenshots immer willkommen.

Zu Teil 1. würde ich meine Mithilfe anbieten, stecke gerade da drin ebenso kann ich was zu FireBird /InterBase beitragen.

Christoph

Alsooo.......

Ich finde eine Doku sollte ein umfassendes Werk sein das alles beinhaltet. Erstinstallation als eigenes Kapitel sicherlich eine super Idee - eine detailierte Installation.

ad Ausführlichkeit stelle ich mir das so vor das jedes mODUL; eINSTELLUNGEN ETC SEHR AUSFÜHRLIOCH GESCHILDERT WIRD. WAS ES MACHT (sorry 4 caps - laptop spinnt ) wie die einstellungen sind und was diese bewirken.

mehr bilder finde ich ist nicht unbedingt notwendig da man sowieso sich durch die ganzen punkte durcharbeiten kann. zudem ist es punktebezogen sicherlich einfacher zu warten als mit pics.

der aufbau wie er jetzt ist gefällt mir eig. ganz gut da man mit der suchfunktion eig. alles ganz gt findet (IE Suchfunktion)...also aufbau modulbezogen und einstellungspunktebezogen....

lg, mong


PS: Eine Art Wiki als Doku ist sicherlich auch keine schlechte idee - einfach zu warten, zu ergänzen und überscihtlich aufgrund der suche.

Hallo,

bin auch gerade dabei, einem System den Feinschliff zu geben und deshalb natürlich oft in der Doku unterwegs.

Den Aufbau finde ich eigentlich hervorragend. Wer möchte, kann sich durch jeden einzelnen Punkt durchwühlen, aber man findet auch schnell nur den Punkt, der einen interessiert.

Ein Kapitel zur Erstinstallation oder technischen Voraussetzungen ist, denke ich, gang und gebe, sollte also drin belassen bzw. noch etwas ausgebaut werden.

Was mir persönlich aufgefallen ist, dass viele Module zwar dokumentiert sind, aber oft lediglich angegeben ist, was man einstellen kann (dies kann man unschwer selbst im System herausfinden) und nicht WOZU es dient oder was die Einstellungen bewirken. So habe jedenfalls ich schon oft davor gesessen und musste schlicht und einfach ausprobieren, was diese oder jene Einstellung so bewirkt (Manchmal sicher auch mit ungewünschten Folgen *g*).

Ich denke, auf diesen Punkt sollte bei einer Überarbeitung mehr Wert gelegt werden.

Grüße, Katja

Da meckern allein nichts hilft, würde ich mich natürlich auch für eine Modulbeschreibung zur Verfügung stellen. Ob jedoch mein Wissen als opn-Anfänger dafür ausreicht, kann ich nicht beurteilen.

Icefee schrieb am 21.09.2007 um 11:20:23 Uhr folgendes:

Da meckern allein nichts hilft, würde ich mich natürlich auch für eine Modulbeschreibung zur Verfügung stellen. Ob jedoch mein Wissen als opn-Anfänger dafür ausreicht, kann ich nicht beurteilen.

Sali Katja,

also ich denke schon dass das ausreicht, weil in dem Fall wo jemand probiert und merkt aha ja da fehlt was das geht so das sollte erweitert werden, derjenige kann jeder Zeit bei dem Kapitel via Kommentar etwas dazu beitragen, was ich dann auch sicherlich übernehmen werde.

Zu den anderen Punkten oben;

1.Installation
hatte ich schon mal darauf angesprochen (lang ist es her) sollte denke ich ein separates Kapitel für sich, wo auch Einstellungen die Server betreffend sind mit angesprochen werden, also szsg. die Voraussetzungen dazu etc.

2. Mehr Text/Bilder
Altbewert denke ich das mehr Bilder immer gut sind, wie schon gesagt wurde, Bilder sagen mehr als tausend Worte.

3. Module
Modulbeschreibung im Fall jedes für sich; so haben wir es bereits. Ebenso die Anfänge welches Modul mit welchen in Zusammenhang arbeitet, arbeiten kann, welche von einander ab/unabhängig sind, mit einführen, ob als Einleitung oder Zusatz. Denke aber auch dort wäre ein Kapitel *Module die zusammen/miteinander arbeiten* (oder so ähnlich)

4. Aufbau allgemein
Nun, die meisten werden eh schon wissen das ich selbst auch mit der jetzigen Lösung wie es nicht völlig zufrieden bin, von daher würde mir persönlich auch eher ein Wiki zusagen, aber wie ich auch schon angedeutet habe, fehlt mir a. schlichtweg auch die Zeit um da eventuell mal zügig was vorwärts zu machen und b. wenn ich nicht sehe das da mitgearbeitet wird, und im Fall nur (sorry) heisse Luft kommt, muss ich gestehen, habe ich keine grosse Lust mich da ran zu setzen und alles neu aufzusetzen

In diesem Sinne erstmal
Gruss Tine

Ich finde beide Varianten gut. Also sowohl die bestehende Doku als auch ein Wiki.

Vorteil bestehende Doku>>> leichtes suchen
Vorteil Wiki>>> alle können sofort mitarbeiten

Vielleicht sollte man beides erstmal paralell machen um dann zu sehen, wo der größere Erfolg ist. Bei nem Wiki wäre ich auf jeden Fall mehr motiviert. Da kann man eben schnell mal was eintragen.

Bilder im Wiki, in der alten Doku weniger.

Wichtig, finde ich, ist eine detaillierte Beschreibung der Module, hatte ich schon mal an Spinne geschickt. Also was kann es, wozu braucht man es. Sollte auch immer verlinkt werden, zum Beispiel bei den Downloads. Dann kann man gleich gucken was man braucht und muß nicht alles nehmen.

In der Doku sollten dann die Module auch detailliert beschrieben werden. Auch Wechselwirkungen und Abhängigkeiten sind wichtig.

Bei den Modulbeschreibungen könnte man auch Links zu How to's machen.

Eine Beginner Seite finde ich auch klasse. Links zu Seiten, wo die Konfiguration von eigenen Servern beschrieben werden. Eine Blacklist von Hostern, die mit OPN nicht können/ wollen, würde ich auch anlegen.


Das war's erstmal, mir fällt bestimmt noch mehr ein.^^

Hi,
es wurde schon fast alles gesagt...
1) Einsteiger-Leitfaden ist ein Muss (sonst lässt jeder gleich wieder die Finger vom neuen System)
2) Dann würde ich ein WIKI hinstellen - das kann ja m.W. jederzeit "restrukturiert" werden, falls notwendig - ohne die Inhalte zu verlieren. Ich würde deshalb weniger Vorab-Überlegungen anstellen wie's aufgebaut sein könnte, sondern ein leeres Wiki hinstellen - und mal sehen was rauskommt.

Hat zumindest bei Wikipedia bestens funktioniert

Ciao,
Boby