Wie dokumentieren?

[Marcel-Andre]

Hallo zusammen,

wir stellen bei uns die Software für die technische Planung der 5 Techniker um und durch den wechsel fällt unsere alte Methode weg zu dokumentieren. Ich suche Ansätze, wie man strukturiert, wenn möglich auch beim Kunden, mit mehren Leute dokumentieren kann. Ich hatte eigentlich an eine Wiki gedacht, aber mir fehlt noch das passende Paket oder der passende Ansatz. Bitte helft mir mal auf die sprünge!

Grüße,

Marcel

[flashpixx]

Wie soll den dokumentiert werden? Sprich was ist das spätere Ergebnis? Soll da eine Doku in z.B. PDF Form heraus kommen oder soll das ganze online verfügbar sein, so dass man es schnell abrufen kann?

Oder soll das ganze eine Kundendoku werden, die der Kunde evtl digital + Papier erhält?

[Marcel-Andre]

Nein, das soll für uns intern sein. PDF-export wäre nice-to-have. Online wäre eher wichtig. Und einfach bearbeitbarkeit.

[Kwaiken]

Warum kein CVS? Ist doch eig. genau dafür gedacht.

[Marcel-Andre]

CVS? Sorry, keine Ahnung!

[Kwaiken]

Du kennst doch CVS ... ? Das System, dass überwiegend für Versionierung von Dokumenten/Programmen/Code/etc. eingesetzt wird an denen mehrere Leute arbeiten? Nachfolger wäre dann SVN, was ein gutes Handling für Binärdateien (Office-Dokumente z.B.) ermöglicht.

Nur kurz zum Grundgerüst als kleiner Crashkurs:

Server:

- CVS/SVN Server aufsetzen (dort liegen die Dokumente)

- kurz CVS/SVN Root und Struktur einrichten

- Benutzer anlegen, Passwörter vergeben

- Den CVS Port oder Rechner per Portforwarding oder 1:1 NAT für das WAN freigeben, so dass auch aus dem Internet darauf zugegriffen werden kann

Clients:

- auf den Clients dann z.B. TortoiseCVS oder TortoiseSVN auf den Windows Clients einrichten, bei Linux und Mac ist es meist schon drauf. Die Programme integrieren sich in die Explorer-Sturktur bzw. in den Konqueror unter Linux.

- Clients schnell konfigurieren und initiales CVS/SVN Checkout der Struktur

Damit hast Du alles erschlagen: du hast freie Software (keine Lizenzkosten), welche unter allen gängigen Betriebssystemen (Win/Lin/Mac) funktioniert, sich bequem in den Explorer/Konqueror integriert (GUI), sicher ist (Zugriff erfolgt über SSL) und deine Anforderungen (gemeinsames Arbeiten an Dokumenten) bequem erfüllt. Dazu eine History jeder Datei inkl. Bearbeiter und Changelog, sowie die Möglichkeit jede Version "auszuchecken", falls ein übereifriger Kollege, als neue Version mal Mist eingecheckt hat.

Lies dich mal ein bisschen in die Links ein.

Bearbeitet 20. Oktober 2010 von Kwaiken

[flashpixx]

@Kwaiken: CVS, SVN und ggf auch Git sind eigentlich nur lohnenswert, wenn er z.B. eine Doku schreiben will. Aber da es ja online verfügbar sein soll, wäre wohl das Wiki die beste Alternative.

Ich denke mit eine CMS / Wiki ist man gut bedient und je nach System hat man einen PDF Export dabei bzw. man kann ihn leicht selbst dazu bauen.

[Kwaiken]

Er will ja unter anderem dokumentieren. Ein wiki bietet da doch nur beschränkte Gestaltungsmoeglichkeiten. Ausserdem kann man ein CVS auch "online" über Web bedienen wenn man keinen Client hat. Sehe immernoch keine Vorteile fur ein wiki.

[flashpixx]

Alle Repository sind dateibasiert, der OP hat hier nichts von Dateien gesagt. Außerdem ist dann die Schwierigkeit, dass die Systeme nicht gut mit binären Daten umgehen können, d.h. ein CVS mit einer Worddatei drin, macht dann wenig Sinn, weil man kein Diff auf die Binärdaten machen kann.

Ein Wiki + entsprechende PDF Generierung z.B. via XSLT und XML:Fo wären sicher von der Funktionalität sinnvoll, denn das Wiki ist für den / die User zur Eingabe gedacht und aus dem Wiki kann automatisiert das PDF generiert werden.

Wenn es ein Repository sein soll, dann muss man auch überlegen welche Daten dort liegen, wenn es um eine reine Dokumentation gehen soll, wäre evtl LaTeX sicherlich in Verbindung mit dem Repository sinnvoll, denn TeX ist textbasiert, die Formatvorlagen können ebenfalls im Rep liegen und die Generierung kann automatisiert erfolgen.

[bigvic]

Er will ja unter anderem dokumentieren. Ein wiki bietet da doch nur beschränkte Gestaltungsmoeglichkeiten. Ausserdem kann man ein CVS auch "online" über Web bedienen wenn man keinen Client hat. Sehe immernoch keine Vorteile fur ein wiki.

Dafür benötigt man doch immer Drittsoftware wie MsOffice,Openoffice,Visio,etc.

Und wie hat man da Standards? Jeder kann doch seine Worddokumente gestalten wie er lustig ist. Der eine benutzt das, der andere andere das .. Inkombatitiliät ist vorprogrammiert.

[Kwaiken]

Dafür benötigt man doch immer Drittsoftware wie MsOffice,Openoffice,Visio,etc.

Nein, ViewCVS z.B. kann Dir dein CVS online anzeigen.

Und wie hat man da Standards? Jeder kann doch seine Worddokumente gestalten wie er lustig ist. Der eine benutzt das, der andere andere das .. Inkombatitiliät ist vorprogrammiert.

*Wenn* Dir die mangelhaften Gestaltungsmöglichkeiten eines Wiki ausreichen und Du dich auf eine Editorform beschränkst (nämlich HTML und als Frontend das Wiki), dann sollte es doch nicht so schwer sein sich auf MS Word oder Openoffice zu einigen, wobei Du mit letzterem selbst die Wort-Dokumente meist problemlos bearbeiten kannst.

Deine propagierte Kompatibilität rührt daher, dass Du dich von Anfang mangels Möglichkeiten an auf eine Bearbeitungsform (eben HTML + Web-Frontend) und einen Export (HTMl + PDF) einschränkst. Wenn Du das gleiche mit SVN machst, dort aber aus mehr Bearbeitungsmöglichkeiten (sogar je nach Datei: Dokumente Word stat OO, Zeichnungen: DIA statt Visio, ...) wählen kannst, hast Du auch keine Kompatibilitätsprobleme.

Also ein selbst erdachtes Problem.

Ich kann - aus Erfahrung - sagen, dass wir mit CVS (jetzt SVN) weitaus bessere Erfahrungen gemacht haben, als mit einem Wiki, welches wir vorher zur Dokumentation verwendet haben.

Alle Repository sind dateibasiert, der OP hat hier nichts von Dateien gesagt.

Doch, er wollte u.U. ggf. einen Dateiexport. Und mir ist es lieber, ich habe die Gestaltungsmgl. eines Word/OO als das eines HTML Editors.

Er kann es ja einfach mal ausprobieren: ein Wiki und ein CVS ist doch schnell aufgesetzt...

Bearbeitet 20. Oktober 2010 von Kwaiken

[flashpixx]

Nein, ViewCVS z.B. kann Dir dein CVS online anzeigen.

Dann würde ich Dich mal bitten mir zu zeigen, wie ich eine Powerpoint Datei, die im SVN / CVS liegt unter Linux mir "online" anschauen kann

Doch, er wollte u.U. ggf. einen Dateiexport. Und mir ist es lieber, ich habe die Gestaltungsmgl. eines Word/OO als das eines HTML Editors.

Du hast nicht verstanden was ein CVS / SVN / Git macht! Du vermischst hier Anwendung und Datenhaltung. Die Reps sind nur für die Datenhaltung gedacht und eine Versionierung, mehr macht ein SVN / CVS / Git nicht.

Zu der Aussage, dass man bessere Gestaltungsmöglichkeiten mit Word hat als mit HTML, halt ich auch für nicht haltbar, denn wenn mein Wiki kein HTML sondern XHTML Dokument erzeugt, dann kann ich es mit XSLT in nahezu jede andere beliebige Form exportieren. Mit XML:Fo kann ich ein PDF erzeugen, das ein völlig anderes Layout erzeugt als im Wiki als HTML Code sichtbar ist.

Wenn Du ein Wordfile in ein CVS / SVN legst, dann ist eine binäre Datei, wenn zwei Leute gleichzeitig ihre lokale Kopie einchecken, dann wird letztendlich eine von beiden Versionen verworfen, denn in binären Datenformaten, wie es Word z.B. ist, kann man kein Diff machen, so dass man beide Änderungen korrekt einpflegen kann. Ein SVN mit binären Daten ist im Grunde völlig sinnlos, da kannst Du direkt ein DMS nehmen. Reps sind letztendlich dafür entwickelt worden, um Quellcodes, d.h. Textdaten zu versionieren.

[Kwaiken]

Dann würde ich Dich mal bitten mir zu zeigen, wie ich eine Powerpoint Datei, die im SVN / CVS liegt unter Linux mir "online" anschauen kann

Ich glaube wir reden aneinander vorbei. Der TE möchte gerne dokumentieren. Und das nach Möglichkeit auch von unterwegs mit seinem Client. Online. Und das macht er mit seinem ... Trommelwirbel... PC (ich gehe mal davon aus, dass er sein Smartphone oder EiPad nicht dazu benutzt)!

Wenn er ohne Zusatzsoftware dokumentieren möchte und Du einen Browser nicht als Zusatzsoftware definierst, die wenigen Gestaltungsmöglichkeiten eines WYSIWYG/HTML-Web-Editors in Kauf nimmt oder nehmen kann (bzw. seine Dokumentationen in XHTML verfassen möchte): perfekt! Denn dort ist auch eine Versionierung vorhanden. Wenn auch nicht CVS/SVN Äquivalent.

Aber möchte er vielleicht etwas mehr (bzw. einfachere) Gestaltungsmöglichkeiten haben und schreibt seine Dokus mit Latex/Word/OO dann hat er das Programm bestimmt auch auf dem Client installiert und kann so problemlos die Daten im CVS/SVN öffnen/bearbeiten.

Du hast nicht verstanden was ein CVS / SVN / Git macht! Du vermischst hier Anwendung und Datenhaltung. Die Reps sind nur für die Datenhaltung gedacht und eine Versionierung, mehr macht ein SVN / CVS / Git nicht.

Nein, ich benutze es nur seit Jahren... aber habe trotzdem keine Ahnung. Es geht dem TE um eine Möglichkeit mit mehreren Leuten an einer Dokumentation (egal in welcher Form) zu arbeiten. Da ist das Wiki eher begrenzend. Das CVS soll auch nicht mehr machen, als eine bequeme Möglichkeit haben eine Versionierung von Dateien vorzunehmen damit mehrere Leute daran arbeiten können.

Zu der Aussage, dass man bessere Gestaltungsmöglichkeiten mit Word hat als mit HTML, halt ich auch für nicht haltbar, ...

Ich kann mir nichts schöneres vorstellen, als meine Dokumentationen in XHTML zu verfassen! Oder in einem abgespeckten Editor. ich drücke es mal anders aus, damit Du dich nicht an Formulierungen festbeissen musst um deine Argumentationskette aufrecht zu erhalten: mit Word/OO hat man es einfacher eine ansprechende Dokumentation zu erstellen, als mit XHTML.

Wenn Du ein Wordfile in ein CVS / SVN legst, dann ist eine binäre Datei, wenn zwei Leute gleichzeitig ihre lokale Kopie einchecken, dann wird letztendlich eine von beiden Versionen verworfen, denn in binären Datenformaten, wie es Word z.B. ist, kann man kein Diff machen, so dass man beide Änderungen korrekt einpflegen kann.

Vielleicht solltest Du dich etwas über SVN informieren? SVN speichert Diffs von Binärdateien (es hat nur Probleme bei größeren Dateien mit ~400 MB). Die alte Version wird nicht verworfen.

Ein SVN mit binären Daten ist im Grunde völlig sinnlos, da kannst Du direkt ein DMS nehmen. Reps sind letztendlich dafür entwickelt worden, um Quellcodes, d.h. Textdaten zu versionieren.

RCS und CVS sind für Quellcode entworfen worden. SVN ist mit dem Hintergedanken entworfen worden, es auch für Binärdateien nutzbar zu machen.

Im Endeffekt stellt sich die Frage: reichen ihm die Möglichkeiten eines WYSIWYG-Web-Editors oder kann er die Feinheiten in der Doku mit XHTML bearbeiten? Ab ins Wiki! Möchte er seine Dokus lieber bequem in Word/OO schreiben, Grafiken mit Visio/DIA machen, PDFs direkt aus dem Dokument erzeugen, und trotzdem nicht auf Versionierung verzichten: Ab ins SVN (oder DMS)!

Bearbeitet 20. Oktober 2010 von Kwaiken

[bigvic]

Wenn er ohne Zusatzsoftware dokumentieren möchte und Du einen Browser nicht als Zusatzsoftware definierst, die wenigen Gestaltungsmöglichkeiten eines WYSIWYG/HTML-Web-Editors in Kauf nimmt oder nehmen kann: perfekt! Denn dort ist auch eine Versionierung vorhanden. Wenn auch nicht CVS/SVN Äquivalent.

Aber möchte er vielleicht etwas mehr Gestaltungsmöglichkeiten haben und schreibt seine Dokums mit Latex/Word/OO dann hat er das bestimmt auch auf dem Client installiert und kann problemlos auf die Daten im CVS/SVN zugreifen.

Du setzt dein Schwerpunkt auf möglichst grosse Vielfalt an verschiedenen Spielereien und Versionierung bei der Dokumentation. Andere setzen sie anderst z.B. Einheitlichkeit (Formate, Standards, CI, ...), Kompatibilität, etc.

Natürlich kann man alles auch organisatorisch lösen, aber das kann man bei der Versionierung ebenfalls. Soll der TE entscheiden war für ihn wichtiger ist.

[Kwaiken]

Du setzt dein Schwerpunkt auf möglichst grosse Vielfalt an verschiedenen Spielereien und Versionierung bei der Dokumentation. Andere setzen sie anderst z.B. Einheitlichkeit (Formate, Standards, CI, ...), Kompatibilität, etc.

Nein, bigvic. Du missverstehst mich (oder ich drücke mich nicht deutlich genug aus). Deine Einheitlichkeit erkaufst Du Dir durch den Einsatz einer Software, die nur bestimmte Dinge zulässt. Du kannst also nichteinmal wählen mit was Du einheitlich sein willst. Beispiel Wiki: Einheitlichkeit durch vorab-Beschränkung durch die Software auf XHTML/WYSWIG-Web.

Mit einer Software, die mir die Wahl lässt, habe ich die Möglichkeit zu entscheiden, mit was ich die Einheitlichkeit erreichen kann. Beispiel SVN: Einheitlichkeit durch nachträgliche-Beschränkung durch mich (oder meine Vorgabe) auf OO/Word/Visio/DIA/...

*Ich* habe also bei einem die Wahl mich auf etwas zu beschränken (oder dein angesprochenes Chaos beizubehalten), beim Anderen bin ich von vornherein auf etwas *durch die Software* beschränkt.

Naja, von meiner Seite ist alles zum Thema gesagt. Muss der TE schauen, mit was er leben kann/will und was für ihn einfacher zu handhaben ist. Alles andere artet in Glaubenskriege aus, die man am besten mit einem Glass Whiskey im Sessel ausdiskutiert

Bearbeitet 20. Oktober 2010 von Kwaiken

[bigvic]

Mit einer Software, die mir die Wahl lässt, habe ich die Möglichkeit zu entscheiden, mit was ich die Einheitlichkeit erreichen kann. Beispiel SVN: Einheitlichkeit durch nachträgliche-Beschränkung durch mich (oder meine Vorgabe) auf OO/Word/Visio/DIA/...

Und wie beschränke ich was jemand wie in OO gestaltet, wenn mein Fokus die Einheitlichkeit der Dokumentation ist? Kann man das mit SVN?

Dast hat nichts mit Glaubenskrieg zu tun, sondern mit Anforderugnen an ein Tool. Wenn SVN das kann, dann ist das evtl. eine gute Alternative (zumindest für mich) - ich wüsste aber nicht, dass das geht.

[Kwaiken]

Und wie beschränke ich was jemand wie in OO gestaltet, wenn mein Fokus die Einheitlichkeit der Dokumentation ist? Kann man das mit SVN?

Du kannst auch in einem Wiki nicht entscheiden, wie jemand dort Dokumentiert. Es sei denn Du sagst explizit: "Halte dich an das Design!". Aber das war's auch schon.

Ich kann aber in einem beliebigen Word-Dokument Formatvorlagen für Kopfzeilen, Fußzeilen, Überschriften und Grafiken ablegen. Dann muss der Bearbeiter sich an absolut nichts halten, sondern einfach in dem Stil Weiterschreiben ohne die Formatvorlagen zu verändern. Für Neudokumente kann ich eine leere Dokumentations-Vorlage mit bereits abgespeicherten Formatvorlagen erstellen und die im SVN ablegen.

Aber wenn jemand "aus der Reihe" springen möchte, kann er das bei beiden Versionierungsarten. Die letztere Bietet mir einfach nur mehr/einfachere Möglichkeiten der Gestaltung als ein Wiki.

[flashpixx]

Du kannst auch in einem Wiki nicht entscheiden, wie jemand dort Dokumentiert. Es sei denn Du sagst explizit: "Halte dich an das Design!". Aber das war's auch schon.

Das ist nicht richtig, wenn das Wiki XHTML Code erzeugt, dann ist die Vorgabe fest, denn sie muss einem gültigen XML Dokument entsprechen. Durch eine XSLT kann ich dann dieses entsprechend meiner Vorgaben transformieren z.B. XML:Fo und daraus ein einheitliches Dokument z.B. PDF erzeugen.

Der Unterschied ist, dass die Layoutvorlage nicht in dem Dokument liegt. Wobei ich das als Vorteil erachte, denn wenn ich irgendwann die Vorlage ändere, dann müsste bei Dir jedes schon geschriebene Dokument angepasst werden, was unter Umständen sehr viel Aufwand ist. Bei der Lösung wie TeX oder XML, ändere ich nur einmal die Vorlage und erzeuge einfach alle Dokumente neu, d.h. ich trenne Inhalt und Layout. Der Inhalt liegt als definierter XML Code vor, das Layout ebenfalls und diese werden durch XSLT zusammengeführt

[Kwaiken]

Wir reden von Pferd und Elefant

Falls Du dich für das Thema interessierst und einer Diskussion nicht abgeneigt bist, schreib mir einfach eine PM. Ich schicke Dir meine ICQ/Skype-Daten. So kann man sich besser auf eine Grundlage einigen und dann zielgerichteter Diskutieren, was beiden Seiten von Vorteil ist, wie ich meine. Du scheinst ja durchaus über Ahnung in dem Bereich zu verfügen, was über bloßes googlen hinausgeht. Ich für ein Gespräch unter Leidensgenossen daher durchaus zu haben

Ansonsten hilft es dem TE nicht weiter, wenn wir uns im Kreis drehen. Er hat 3 Möglichkeiten: Wiki oder SVN/DMS und kann alles innerhalb einer halben Stunde problemlos aufsetzen und schauen, was seine Anforderung am besten erfüllt.

Bearbeitet 20. Oktober 2010 von Kwaiken

[KuhTee]

Kwaiken, du schreibst die ganze zeit von CVS. Allein das disqualifiziert einen doch schon...

Und im endeffekt haben alle, die dir widersprochen haben, recht. CVS ist kein system für eine dokumentation, auch nicht in zusammenarbeit mit Word. Meine güte, was habe ich überzeugungsarbeit bei mir auf arbeit leisten müssen, bis endlich diese elenden word-dokumentationen in den mülleimer gekickt wurden. Zugegeben, das waren entwicklerdokumentationen (schnittstellen, funktionen etc), aber auch bei anwenderdokumentationen ist word einfach dreck.

Ein mergen ist bei grösseren änderungen praktisch unmöglich. Layout ändern? Oje... Exportieren? Bei mehr als PDF wirds übel. Über scripte verarbeiten? Kann man vergessen.

Die besten dokus schreiben sich mit formaten die ich

a) einfach mergen kann

einfach per selbst geschriebenen programm verarbeiten kann

c) export in beliebige formate zulassen

Da bleibt am ende nur ein format wie latex und vergleichbare tag-basierte systeme. Dann auch gern mit SVN oder ähnlichem (bloss kein CVS!). Der ganze von wegen "man kann seiner gestaltungswut nicht freien auf lassen" ist sowieso totaler mumpitz, da eine dokumentation ein vorgegebenes format hat. Da hat keiner regenbogen-schrift mit schatten reinzubauen.

[Kwaiken]

KuhTee: bevor ich mir Sorgen mache würde, was andere wann disqualifiziert sollte ich mir Sorgen machen ob ich Lesen kann. Denn das kannst Du offensichtlich nicht. Ansonsten wäre Dir aufgefallen, dass ich von SVN als Weiterentwicklung des CVS rede wenn es um Binärdateien geht und von CVS selbst wenn es um Quellcode/Plaintext geht. Aber Hauptsache was rausgerotzt, ne?

Jemandem, der bei Dokumentation an ein Wiki denkt und dem CVS kein Begriff ist, dem kommst du mit Latex für die Doku? Ich glaube Du hast den Schuss nicht gehört... ich schreibe meine Facharbeiten für die Uni mit Latex weil ich muss; vernünftige Formeln gehen nur damit. In der Wirtschaft, wo für die Doku sowieso nicht viel Zeit bleibt, auch noch mit Latex zu dokumentieren... Du bist weit weg von der Realität in den meisten Betrieben. Oder hast das Glück, das Dir genug Zeit dafür zugestanden wird.

Bei 5 Technikern reich IMHO SVN + OO. So einfach wie möglich, so flexibel wie möglich. Wäre mein Vorschlag. Bigvic und flashpixx halten Wiki, aus den von ihnen vorgebrachten Gründen, für sinnvoller (kann ich nachvollziehen). Möge der TE entscheiden, was ihm passt. Oder ob er und seine Kollegen sich in Latex einarbeiten *Kopfschüttel*

IMHO ist hier alles gesagt, was (manches mehr, anders weniger) sinnvoll ist. Der TE kann nun schauen, mit was er zurecht kommt.

Bearbeitet 22. Oktober 2010 von Kwaiken

[flashpixx]

ich schreibe meine Facharbeiten für die Uni mit Latex weil ich muss; vernünftige Formeln gehen nur damit.

Da schließe ich mich komplett an, bei mir in der theoretischen Informatik geht ohne TeX gar nichts.

In der Wirtschaft, wo für die Doku sowieso nicht viel Zeit bleibt, auch noch mit Latex zu dokumentieren... Du bist weit weg von der Realität in den meisten Betrieben. Oder hast das Glück, das Dir genug Zeit dafür zugestanden wird.

Dem kann man eigentlich auch so zustimmen, Doku wird meistens "geschlabbert", weil es eben nichts ist, was Geld einbringt

Wäre mein Vorschlag. Bigvic und flashpixx halten Wiki, aus den von ihnen vorgebrachten Gründen, für sinnvoller (kann ich nachvollziehen). Möge der TE entscheiden, was ihm passt. Oder ob er und seine Kollegen sich in Latex einarbeiten *Kopfschüttel*

Ich denke ich würde hier keinen vollständigen LaTeX Satz einzubringen. Was ich für sehr sinnvoll erachte: Der Quellcode muss für den Entwickler eh dokumentiert werden, d.h. da kann man - finde ich ganz gut - Doxygen verwenden. Aber oft braucht man noch eine Userdoku, wobei ich diese eben in TeX machen würde, d.h. ich würde in den Quellcode z.B. einer Form ein spezielles Tag einfügen in dem ich dann einfach den Text für dieses Form schreiben würde. Da der Code in einem System wie SVN / Git liegen sollte, kann ich einfach, wenn ein neuer Branche erzeugt wird, nach dem Text in im Quellcode greppen einmal via TeX die Userdoku erzeugen und einmal via Doxygen die Entwicklerdoku

Ob man jetzt konkret TeX nimmt, sei freigestellt, als Alternative wäre ja DocBook ? Wikipedia denkbar. Mir ist in meiner Berufszeit immer aufgefallen, dass eigentlich der Entwickler am besten beschreiben kann, was seine Form macht oder wie etwas einzustellen ist, d.h. für mich wäre da der Ansatzpunkt (man kann ja auch das ganze noch mehrstufig ausbauen, d.h. Quellcode => Lektoriat / Korrektur => Doku). Ich muss halt dem Entwickler die Möglichkeit geben möglich "kurz" und "leicht" die Doku einzubinden. Da er eh den ganzen Tag den Quellcode offen hat, wäre dort der Ansatz. Wenn ich das einmal habe, dann kann ich die Doku immer aus den Sources ziehen und ggf dann ja noch weiter verarbeiten.

Das Wiki wäre die Alternative für Cofigs von Hardware, da man dort ja meistens nicht per SVN o.ä. ran kommt bzw. in die Config nicht immer kommentieren kann. Darum eben ein Wiki, was dann aber wie gesagt, weiter verarbeitet wird.

Ziel sollte es immer sein, dass der Entwickler / Admin möglichst wenig Zeit in die Doku stecken muss und das ein einheitliches Bild entsteht, was sich auch leicht ändern lässt.

Bearbeitet 23. Oktober 2010 von flashpixx

[disarstar]

Wenn ich mir die Anforderungen durchlese komme ich zu 2 Schlüssen

entweder

1. ein selbstaufgesetztes Wikisystem

2. oder ein sonstiges CMS System (typo3 oder sonstige)

Haben zu Dokuzwecken beispielsweise wordpress zweckentfremdet.

Begründung:

1. Sehr gute Suchfunktion

2. einfaches Template System

3. einfache Anbindung eigener Plugins

4. Benutzerverwaltung

5. Möglicher Passwortschutz(...)

uvm.

Das ist jedenfalls meine Meinung dazu

[KuhTee]

Ansonsten wäre Dir aufgefallen, dass ich von SVN als Weiterentwicklung des CVS rede wenn es um Binärdateien geht und von CVS selbst wenn es um Quellcode/Plaintext geht. Aber Hauptsache was rausgerotzt, ne?

Offenbar sind die die unterschiede zwischen CVS und SVN nicht ganz klar... Wen jucken binärdateien? Mergen kann ich die in beiden nicht, wenn mir nicht dritt-tools was brauchbares zur verfügung stellen. Und word-dokumente (DARUM ging es dir ja primär) zu mergen ist kein spaß.

Ich glaube Du hast den Schuss nicht gehört... ich schreibe meine Facharbeiten für die Uni mit Latex weil ich muss; vernünftige Formeln gehen nur damit. In der Wirtschaft, wo für die Doku sowieso nicht viel Zeit bleibt, auch noch mit Latex zu dokumentieren... Du bist weit weg von der Realität in den meisten Betrieben.

Wo wir beim lesen waren, nicht wahr? Ich sagte "und vergleichbare tag-basierte systeme". Ich persönliche bervorzuge doxygen, das ist aber eher was für entwicklerdokumentation.

Das es mir vor allem gegen word ging, ist die nicht aufgefallen? Dann nochmal zum mitmeißeln: word für dokumentation (die noch dazu von mehreren leuten gleichzeitig geschrieben wird) ist ein einziger dreck. Und vollkommen unnütz dazu. Es gibt kein einziges sinnvolles argument pro word wenn es um eine dokumentation geht. Vorausgesetzt natürlich wenn man es richtig machen will. Schnell hingeschmiert (wie es leider viele machen), das geht natürlich am besten in word.

[dano0b]

schau dir einfach mal Open Source Enterprise Content Management System (CMS) by Alfresco an, ggf. ist es etwas für euch. bietet viele möglichkeiten.