Re: [OT] Dokumentation erstellen
- From: Peter Büttner <not_for_mail_peb@xxxxxxx>
- Date: Wed, 27 Jul 2005 13:57:24 +0200
Timo Stamm wrote:
> Peter Büttner wrote:
> > Stefan Matthias Aust wrote:
> >>Ein bisschen OT, aber mich würde interessieren, was ihr so benutzt, um
> >>Programmdokumentationen zu erstellen? Einfach Word? Oder HTML? Docbook?
> >>Was anderes?
> >
> >
> > Im Moment Office (MS Word).
> >
> >
> > Da wollte ich eh' schon mal drüber reden.
> >
> > Eigentlich würde mir ein Wiki gefallen, das MediaWiki sieht gut aus.
>
> Mit dem MediaWiki haben wir in einem Team von 6 Leuten sehr gute
> Erfahrungen gemacht. Es ist ein ideales Medium, um mit mehreren Leuten
> umfangreiche Dokumente zu erstellen.
Klingt schonmal gut.
> Die Strukturierung wird einem vom Wiki nicht abgenommen, auf der anderen
> Seite macht eine automatische Strukturierung auch nur in wenigen Fällen
> Sinn und schränkt stark ein. Im Wiki lässt sich beobachten, dass die
> Struktur im Laufe der Zeit "wächst".
Etwas Hierarchisches scheint mir beim mediawiki zu fehlen, das kann man
per vereinbarung machen. Wobei Kategorien sowas in die Richtung ist,
bischen 'härter' wäre aber schon recht. Das ganze kann ja trotzdem noch
netzartige Verweise haben. Aber wenn man Dokumente die sich als
Ergebnis herauskristallisieren in solch eine 'Buchform' zwängen lassen
wäre das gut. Hmm, wikibooks klingt danach, vielleicht sollte ich das mal
anschauen.
> Änderungen lassen sich sehr gut nachvollziehen, sind Personen
> zugeordnet, können mit einem Kommentar versehen und ggf. rückgängig
> gemacht werden.
Für kleine Teams braucht man wohl keine Rechteverwaltung, wer Mist
baut fliegt:-). Wäre aber auch nett sowas wie 'Endgültiges Dokument'
damit nicht einer noch was rumändert.
> Wir benutzen das Wiki für Pflichtenhefte, Spezifikationen und
> Dokumentationen und allgemeines "Knowledge-Management".
>
> > Da ein Wiki auch nicht soviel Layout möglich macht stehen die Inhalte
> > mehr im Vordergrund. Wobei mir html sehr recht ist, kann ich und sollte
> > jeder im it Bereich so bischen können, brauche also das wiki Markup
> > wohl nicht. Die Einfachheit ist ein Punkt.
>
> Ich kann nur davon abraten, HTML anstatt des Wiki-Markups zu benutzen.
> Der Wiki-Markup ist wirklich extrem simpel, lässt sich schnell lernen
> (einfach mal auf "bearbeiten" bei einer wikipedia.org Seite klicken) und
> bietet viele Extras (zum Beispiel wird aus Überschriften automatisch ein
> Inhaltsverzeichnis eines Artikels generiert).
Mag ja sein, aber für mich ist html halt einfach. Und nimmt das Ding
h1,h2,h3 etwa nicht zur generierung des Inhaltsverzeichnis?
Aber macht ja nix, kann man ja beides nehmen. Oder wenn man ein
Dokument in einem html editor schreibt/vorbereitet, könnte man
dann einfach reinkopieren. Wenn z.B. doch etwas komplexere Tabellen
nötig werden.
> Nachteile gibt es natürlich auch, vor allem der Export ist ein Problem.
> Es gibt keine gute Möglichkeit, aus einem Wiki ein PDF Dokument oder
> auch nur eine eigenständige HTML Seite zu machen. Export nach XML ist
> nur rudimentär vorhanden.
Der Export nach xhtml beim mediawiki ist ja schon da, selbst ein xml
rendern will/brauch ich nicht. Wie's geht: einfach mit dem Browser
aufmachen,
oder mit anderer Software abholen. Dann ein xslt drauf und die Navigations-
elemente rausschnippseln => schon ist das Dokument fertig. Bilder muß man
halt noch so abholen. Hier wäre es nett wenn man eingebettetes svg/emf/...
das im Browser als bitmap angezeigt wird im Original abholen könnte.
(Ich weis nicht ob da bereits svg/emf umgewandelt wird, wäre aber eine nette
Ergänzung)
Wenn man Doku als einzelnes Dokument (word/pdf) braucht ist so ein
Export wichtig. Ließe sich wohl recht leicht automatisieren.
Ich würde auch gerne externe Dokumente dranhängen, das ist unvermeidbar.
Die sollten auch Versioniert werden. Und wenn man es shcon mal hat
auch gleich noch die jars selbst (oder was man so produziert),
Naja, Links auf ein anderes Repository wäre auch ok.
> Ggf. ist es natürlich möglich, einfach das Wiki öffentlich zugänglich zu
> machen. Bei Dokumentationen wird das ja von einigen OSS Projekten
> vorgemacht.
An solche Projekte dachte ich nicht,
da passt es eh: halt 'nicht so wichtig':-) darf also auch deutlich hakeln
Grüße
Peter
--
Shell&Jar : Individual icons for jars
jMineSweeper : extended
www.PeterBuettner.de
.
- References:
- [OT] Dokumentation erstellen
- From: Stefan Matthias Aust
- Re: [OT] Dokumentation erstellen
- From: Peter Büttner
- Re: [OT] Dokumentation erstellen
- From: Timo Stamm
- [OT] Dokumentation erstellen
- Prev by Date: Re: Problem beim starten eines jar
- Next by Date: Re: [OT] Dokumentation erstellen
- Previous by thread: Re: [OT] Dokumentation erstellen
- Next by thread: Re: [OT] Dokumentation erstellen
- Index(es):
Relevant Pages
|
