Einstellungen/Konfigurationen dokumentieren

[Duff]

Hallo,

ich will mir angewöhnen mal alles zu dokumentieren, wenn ich auf meinem Server was eingerichtet habe.

Z.B. habe ich mir zur Einrichtung von DHCP mit DynDNS meine Konfiguration in OpenOffice zusammen geschrieben.
Allerdings habe ich bei der Erstellung des Inhaltsverzeichnisses, der Struktur und Formatierung so meine Probleme.
Es ist nicht gerade übersichtlich und die Formatierung (wie z.B. originale Code-Ausschnitte) sind nicht einheitlich.


Wie macht ihr das?
Welche Tools/Software benutzt ihr?

Es gibt doch sicherlich was besseres, um seine Einstellungen zu Dokumentieren.
(Vielleicht in Latex, oder eine Art Wiki, oder...)


Bin mal auf eure Antworten gespannt...


Danke & Gruß,
Daniel

[roli]

Hi,

ich nutze meistens auch OOo, oder auch einfache Texte Dateien. Ab und an versuche ich's auch mal mit /dev/brain, aber das ist was Langzeitarchivierung angeht, bei mir jedenfalls, nicht immer die beste Loesung.
Egal wie deine Dokument aussehen, "alles ist besser als nichts"!
Wenn du ein Wiki nehmen wuerdest, muesstest du dann ja im Wiki beschreiben wie du's eingerichtet hast ;-}

[Duff]

Hi,

ich nutze meistens auch OOo, oder auch einfache Texte Dateien. Ab und an versuche ich's auch mal mit /dev/brain, aber das ist was Langzeitarchivierung angeht, bei mir jedenfalls, nicht immer die beste Loesung.
Egal wie deine Dokument aussehen, "alles ist besser als nichts"!

Das ist wohl war und leider mache ich es auch nicht immer, da es doch sehr zeitintensiv ist.
Aber ich will es mir angewöhnen!!!

Wenn du ein Wiki nehmen wuerdest, muesstest du dann ja im Wiki beschreiben wie du's eingerichtet hast ;-}

Richtig, und hier stellt sich für mich die Frage, wie man am sinnvollsten diese Sachen festhalten sollte.
Wiki, Office-Dokument, Text-Datei, etc.

Eventuell gibt es schon fertige Templates, die man nutzen kann, die vielleicht auch eine gewisse Grundstruktur und gegliederten Aufbau haben!?

[Lirion]

Als Dokumentation habe ich in einer Firma mal ein Mediawiki aufgesetzt. Das Ganze ist anfangs sehr zeitintensiv, sprich das Aufsetzen des Basis"netzes" (Boxen, Links, bla); danach lohnt sich's aber.

Ziel einer Dokumentation sollte zentrale Erreichbarkeit sein, also ne kleine Groupware oder sowas in die man dann PDFs, LaTeX-Doks etc reinlädt, ist auch net verkehrt.

[roli]

Eventuell gibt es schon fertige Templates, die man nutzen kann, die vielleicht auch eine gewisse Grundstruktur und gegliederten Aufbau haben!?

Damit würdest du dich aber in ein Korsett zwaengen, das dir ggf. nicht passt.
Ist das ganze ausschliesslich fuer dich, oder soll's fuer ein Team sein? Schau dir doch einfach mal an was du/ihr schon an Doku erstellt habt, und versuch hierin die Gemeinsamkeiten zu ermitteln. Also z.B.
-wer hat's gemacht
-kurzbeschreibung
-Problemursache
-Datum & Uhrzeit
-Beteiligte Rechner, Komponenten, ...
-ggf. beteiligte Kollegen, externe Mitarbeiter, Mitarbeiter des Providers, ...
-was wurde gemacht

[Duff]

Es ist in erster Linie für mich gedacht, da ich die Dokumentation auch erstellt habe. Es ist für den privaten Gebrauch gedacht und wenn die Artikel gut dokumentiert sind, würde ich sie auch gerne der Allgemeinheit zur Verfügung stellen.

[gOtNoPhEaR]

Also ich mach mir für sowas ne Vorlage für OOo. Wenn man sich da nen paar Vernünftige Formatvorlagen anlegt sollte das schon ganz gut passen.
Ich pack mir dann immer aus dem vi den plaintext rein. Dann einfach Absätze markieren und Formatvorlagen zuweisen. Export in PDF klappt ja auch mehr als gut =)
Am besten ist es, denke ich, immer irgendwie nen Plaintext zu haben, auf den man dann die gewünschte Markup-Sprache anwenden kann. Im Endeffekt kann dan jeder relativ einfach sein gewünschtes Format draus machen.

[Duff]

Also ich mach mir für sowas ne Vorlage für OOo. Wenn man sich da nen paar Vernünftige Formatvorlagen anlegt sollte das schon ganz gut passen.

Hast du eventuell ein Beispiel?

[gOtNoPhEaR]

Bin erst in ein paar Tagen wieder zu Hause.
Aber unter http://www.ooowiki.de/FormatVorlagen ist es ganz gut beschrieben.

Ich habe mir dann eben die Formatvorlagen für die Überschriften angepasst. Eine Formatvorlage für Code erstellt (halt mit fixed Font / kleinere Schriftgröße / andere Farbe). Dann eben noch Vorlangen für URIs, Zitate etc.
Aber kann dir auch bei Gelegenheit mal ne Doku zukommen lassen.

[Duff]

Aber kann dir auch bei Gelegenheit mal ne Doku zukommen lassen.

Das wäre nett.

Schicke dir ne PM wegen der Mail-Adresse.

[Asparagus]

Hi,

ich denke, zim oder Kjots oder basket wären die Anwendungen deiner Wahl...

[Duff]

Hi,

ich denke, zim oder Kjots oder basket wären die Anwendungen deiner Wahl...

Habe mir nun mal zim und basket angeschaut. Da ich gnome benutze habe ich kjots nicht installiert, wobei basket wohl auch eine kde-Anwendung ist.
Die Tools sehen ganz nett aus, sind aber meiner Meinung nach eher als Notizblöcke gedacht.

Ich suche eigentlich mehr was womit ich Dokumentationen erstellen kann. Z.B. die Einrichtung von DHCP mit DDNS.

[Mr_Snede]

Basket scheint mir im Moment keine große Zukunft zu haben:
--> http://www.pro-linux.de/news/2009/14162.html

Vielleicht ist Trac(Wiki) etwas für dich.
--> http://trac.edgewall.org/
Da ist ein Versionskontrollsystem mit eingebaut, in denen du deine Configs einpflegen könntest. Dann gibst du in guter Entwicklermanier deine Kommentare zum jeweiligen Versionstand der Dateien ab. Wenn du mal mehr Infos brauchst, verlinkst du dazu eine Wikiseite.

Ansonsten mag ich Dokuwiki oder am allerliebsten Textdateien maximal mit einer einfachen Syntax (wikicreole, markdown, ...)
um die Dateien auch mal hübsch in html / PDF zu haben

cu Mr_Snede

[Saxman]

Es gibt doch sicherlich was besseres, um seine Einstellungen zu Dokumentieren.
(Vielleicht in Latex, oder eine Art Wiki, oder...)

Die Änderungen in /etc verfolge Ich mit etckeeper, das baut auf git auf.
Kurze Dokumentationen schreibe Ich als Notitzen mit tuxcards und für größere Sachen ist lyx einfach genial.
Das kann Änderungen verfolgen, baut auf tex auf und ist wirklich klasse im Strukturieren.

[xdanx]

und wenn die Artikel gut dokumentiert sind, würde ich sie auch gerne der Allgemeinheit zur Verfügung stellen.

dann würde ich es gleich in ein Wiki schreiben. Wenn du es danach veröffentlichen willst, ist das dann nur noch copy&paste

PS: Ich nehme DokuWiki dafür

[Duff]

Ansonsten mag ich Dokuwiki oder am allerliebsten Textdateien maximal mit einer einfachen Syntax (wikicreole, markdown, ...)
um die Dateien auch mal hübsch in html / PDF zu haben

Ich denke, ich werde mir mal Dokuwiki anschauen.
Wurde ja schon des öfteren hier erwähnt.

Aber was meinst du mit Textdateien, die eine einfache Syntax haben?

Kurze Dokumentationen schreibe Ich als Notitzen mit tuxcards und für größere Sachen ist lyx einfach genial.

Sieht fast noch komplizierter aus als Latex und ist wohl eher was für mathematische Dokumente (Studium).

[Saxman]

Sieht fast noch komplizierter aus als Latex und ist wohl eher was für mathematische Dokumente (Studium).

Ich finde es ist sehr einfach zu lernen und Tex Codes können beliebig verwendet werden.
Vorher hat mich Latex immer abgeschreckt. Das hat sich durch lyx gelegt.
Schau dir einfach mal die screencasts auf der website an.

Aber du hast recht. Es ist eher für wissenschaftliche Publikationen und längere Dokumente, wobei die nicht unbedingt mathelastig sein müssen damit lyx seine Vorzüge ausspielt.
Eine Dokumentation die evtl später gedruckt oder als pdf exportiert wird ist mit lyx sicher auch besser zu schreiben als mit einem wiki. Wenn du aber ein wiki suchst ist es sicher das falsche.

[Mr_Snede]

Aber was meinst du mit Textdateien, die eine einfache Syntax haben?

Damit meine ich Textdateien, die mit wenigen Auszeichnungselementen etwas aufgepeppt werden. Damit man sie sowohl als Textdatei gut lesen kann, wann man aber mag auch in was hübschen umwandeln kann.
Bei mir sieht das dann so in etwa aus:

Code: Alles auswählen

=== config files ===

== /etc/apt/sources.list ==

  # Lokale Paketquelle
  deb file:/pfad/zu/freigabe hardy main
  # CD-Rom Eintrag (hier: Ubuntu Hardy Heron 8.04 i386-Version)
  deb cdrom:[Ubuntu 8.04 _Hardy Heron_ - Release i386 (20080423)]/ hardy main restricted


* This is a list
  * The second item
    * You may have different levels
  * Another item

| Heading 1      | Heading 2         | Heading 3          |
| Row 1 Col 1    | Row 1 Col 2     | Row 1 Col 3        |
| Row 2 Col 1    | some colspan (note the double pipe) ||
| Row 3 Col 1    | Row 2 Col 2     | Row 2 Col 3        |

**fetter Text**
__unterstrichen__  

Das ist auf Basis von Dokuwiki, Mit den Auszeichnungen für Überschriften, Quelltext, Liste, Tabelle und zum hervorheben von normalem Text eben fett und unterstrichen.
Das kann man sich merken ohne nachzuschlagen. Also einfach runterschreiben und man hat einheitlich aussehende Infodateien, die man als Wikiseite anzeigen, oder in irgendwas anderes umwandeln kann. bei Dokuwiki gibt es genügend Plugins fü sowas.

Andere Auszeichnunssprachen gehen auch, sind eher Geschmackssache als wirklich unterschiedlich.

[Duff]

Hört sich und sieht auf den ersten Blick wirklich recht einfach aus.
Werde mir dokuwiki wohl mal installieren und ausprobieren.

Vielen Dank nochmals.


Werde dann später nochmal posten, ob ich auch wirklich damit zufrieden bin.

[goeb]

Ich verwende für meine Konfigurations-/Installations- etc. Dokumentation TiddlyWiki (http://www.tiddlywiki.com/). Alles in einer Datei, kann also auch leicht auf andere Systeme kopiert werden, und braucht keine Installation.

(Ich habe eine etwas angepasste Version davon, andere Stylesheets, und ein paar Plugins, teilweise auch etwas angepaßt, falls du dir die mal anschauen willst, schick mir ne PM.)

MfG, gœb

[LessWire]

Auch wenn man mich nach den vielen professionellen Vorschlägen gleich prügelt:

Meine privaten Dokus fließen in eine einfache Textdatei - mittlerweile seit Jahren, etwa so (Beispiel):

Code: Alles auswählen

------------------------------------------------------------------
IPTABLES: FIREWALL ERSTELLEN
... beliebig lange Beschreibung ...
------------------------------------------------------------------
NÄCHSTES THEMA
... dto. ...
------------------------------------------------------------------
...

Kein Overhead, leicht aus allen möglichen Umgebungen zu bearbeiten und bei triftigen Schlagworten wird auch schnell gesucht und gefunden.

Später lässt sich diese simple Struktur leicht maschinell bearbeiten und z.B. eine chice latex Doku daraus machen.
Wichtig ist mir, diese "ungeliebte" Tätigkeit schnellstmöglich zu erledigen - es sind ja vorerst nur persönliche Notizen - ist mir lieber, als jedes System, daß einen dann doch wieder in ein bestimmtes Format presst und die Flexibilität nimmt.
Keep it simple!

vg, LW

[Duff]

So eine Textdatei habe ich auch. Aber bei mir stehen das bisher immer nur die Sachen, die ich mir nicht merken kann. Die Textdatei hat den Namen kleine_Helferlein.txt.

Lange, ausführliche Dokumentation möchte ich aber in Zukunft mit einem der vielen vorgeschlagenen Möglichkeiten festhalten. Für welche ich mich entscheide, weiß ich noch nicht, da ich die einzelnen Tools noch probieren muss.

[novalix]

Die Änderungen in /etc verfolge Ich mit etckeeper, das baut auf git auf.

Jap, etckeeper ist cool. "Baut auf git auf" ist allerdings etwas ungenau. Git ist das voreingestellte VCS. Man kann aber auch mercurial, darcs oder bazaar benutzen. Letztlich ist die Idee, Konfigurationsdateien unter Versionskontrolle zu stellen, auch nicht so neu. Hat man vor einigen Jahrtausenden schon mit rcs gemacht. "Distributed" ist aber ne ganz andere Qualität.
Interessant wäre jetzt noch eine Ausweitung auf .configs, ohne das ganze /home/user zu erfassen.

Wo wir gerade bei Joeyware(TM) sind. Textdateien, die mit markdown formatiert sind, kann man natürlich auch einfach mit ikiwiki kompilieren und weil es sich anbietet, unter Versionskontrolle stellen, z.B. git-core

Groetjes, niels

PS: Ich liebe diese "deb" Tags. debtags sollte man sich auch mal angucken.