Webbasierte Dokumentation

[weshalb]

Hallo, ich suche eine webbasierte Dokumentationssoftware, womit ich meine Dokumentationen schreiben und indexieren kann.

Bisher schreibe ich alles in txt.Datein und lege diese in beschriftete und nummerierte Ordner ab. Langsam wird das ziemlich unübersichtlich.

[eggy]

Magst mal genauer beschreiben, was Du Dir vorstellst? Sonst würde ich nur sagen "Wiki", und die gibts auch in über hundert Geschmacksrichtungen und Komplexitätsstufen.

[Dogge]

Meinst du so etwas: http://www.sphinx-doc.org/en/stable/

[r4pt0r]

https://readthedocs.org/

Hat auch direkte hooks z.b. zu github, dann ist ausser dem commit kein weiterer arbeitsschritt nötig.

[Lord_Carlos]

Also sowas wie Google Docs zum selber hosten?

[hikaru]

doxygen?

[weshalb]

https://readthedocs.org/

Hat auch direkte hooks z.b. zu github, dann ist ausser dem commit kein weiterer arbeitsschritt nötig.

Genau sowas meine ich. Schaue mir aber auch Sphinx Docs und doxygen nochmal an.

[weshalb]

Ich habe mich der Übersicht halber dann doch für Mediawiki entschieden. Zwar muss ich jetzt alle Texte in der Syntax abändern und dort einfügen, doch der Aufwand lohnt sich.

[r4pt0r]

Ich habe mich der Übersicht halber dann doch für Mediawiki entschieden. Zwar muss ich jetzt alle Texte in der Syntax abändern und dort einfügen, doch der Aufwand lohnt sich.

Ich musste vor einiger Zeit etliche Seiten aus einer Dokuwiki in horde wicked übertragen - mit einem kurzen AWK-script ist das ziemlich fix erledigt.

[uname]

Ich musste vor einiger Zeit etliche Seiten aus einer Dokuwiki in horde wicked übertragen - mit einem kurzen AWK-script ist das ziemlich fix erledigt.

Sehe ich genauso.

Ich würde mir bei einer Entscheidung ernsthaft überlegen ob es wirklich ein Datenbank-orientiertes Wiki (z.B. Mediawiki) oder ein Datei-orientiertes Wiki (z.B. DokuWiki) sein soll. Spätestens wenn du die Daten mal backupen/restoren oder portieren willst oder musst könnte eine Entscheidung für ein Datei-orientiertes Wiki von Vorteil gewesen sein. Wobei Backup und Restore sind ja noch recht einfach. Eine Portierung wäre schon weit schwiedriger (bei Mediawiki).Hier mal zum Vergleich nur Backup und Restore, welches man zwingend von Zeit zu Zeit braucht.

DokuWiki:
Backup und Restore: https://www.dokuwiki.org/faq:backup
(Since DokuWiki does not use a database, backups are really simple. All you need to do is copy the files. The easiest way is just to backup your whole DokuWiki directory. )

Mediawiki:
Backup: https://www.mediawiki.org/wiki/Manual:B ... _a_wiki/de
Restore: https://www.mediawiki.org/wiki/Manual:R ... rom_backup


Weiterer Vorteil von DokuWiki ist, dass man sogar Offline mit den Daten arbeiten kann bzw. es einfacher ist auf einem Linux-Desktop eben einen Apache2 hochzuziehen als zusätzlich noch eine nervende MySQL-Datenbank, die kein Mensch bei so wenigen Daten braucht. Gilt im übrigen auch für Datei-basierte CMS-Systeme wie Typesetter oder CMSimple gegenüber Joomla.

[weshalb]

Im Moment ist es so, dass ich die Datenbank täglich per Rsnapshotscript mitsichere. Ich habe den Dump zum Test auch mehrfach von einer virtuellen Maschine hin und her geschoben und es funktionierte bisher ohne Probleme. Auch nachdem ich die Wikiinstallation gelöscht und neu angelegt hatte und beim Erstaufruf die Datenbank angab, funktionierte es prima.

Was mich erst jetzt nach deinem Hinweis wurmt, ist die Tatsache mit der Offlinemöglichkeit. Bisher ist es so, dass ich meine Dokumentationsdateien immer überall mit hinnahm und vor Ort irgendwo aufrufen konnte. Klar kann man jetzt das Wiki auch extern per Passwortabsicherung nutzen, doch was ist, wenn vor Ort kein Internet vorhanden ist?

Das ist in meinen Augen der klare Pluspunkt für DokuWiki. Doch irgendwie fand ich einfach keine vernünftige Demo, so dass ich mich erstmal mit MediaWiki vertraut machte. Jetzt da wieder umzuswitchen wäre schwierig, da ich schon fleißig seit Tagen schreibe und importiere.

Auch ist mir jetzt der ganze Konfigkram (bin an der nachträglichen Https Konfiguration gescheitert) viel klarer. Das ist ne echt tolle Sache und es hilft mir in der Zukunft ungemein bei der Suche. Ich ärgere mich schon darüber, das nicht früher auf dem Schirm gehabt zu haben.

[ThorstenS]

Früher (~2002) hatte ich das auch im mediawiki - das stand mir aber nicht überall zur Verfügung, bin dann dohc wieder auf plain-text Dateien zurückgefallen.

Ich hab das Problem dann lange vor mir her geschoben, meine Doku verteilte sich auf eine mittlere dreistellige Zahl an Dateien.
Bis vor einigen Monaten hab ich dann mit glimpse zur Volltextsuche auf der console gearbeitet. (ist nach sarge aus debian geflogen, das deb ließ sich aber bis jessie noch bauen).

Dann habe ich Markdown für mich entdeckt, das ich schnell flüssig schreiben konnte. Ich arbeite in der 4ma mit sphinx und lasse die Markdown Dateien nach html/epub/pdf/html und man-page(!) exportieren. Umfangreicheren Export bei weniger Arbeitsaufwand geht nicht. Und das read-the-docs Theme gibt es auch im repo: python-sphinx-rtd-theme

Für mich privat rendere ich die Seiten mit pandoc oder dem atom-Editor mit Live-Vorschau und dann html/pdf Export. Das ganze liegt in einem git-repo und wird nach gitlab.com geschoben. Dort habe ich meine Volltextsuche im Browser.

pandoc kann dir mediawiki-syntax nach markdown konvertieren

[uname]

Also ich finde Markdown [1] ist ein guter Kompromiss.
Da man heute alles mit Javascript programmiert, kann man z.B. einfach Markdown zu "HTML" konvertieren [2].
Vielleicht sind Javascript-basierte Markdown-Wikis [3] ein Blick wert. Ist ja nur eine HTML-Datei und eine config.json.
Das optionale Menü kann man in config.json deaktivieren, das HTML-Design in index.html ändern. Es gibt ein paar Beispiele.
Links auf weitere Markdown-Dokumente wie [readme](readme.md) funtkionieren problemlos.

Es ist aber wichtig die Daten dann wirklich nur als Markdown zu speichern und die genannten Hilfsmittel wirklich als Hilfmittel zu sehen.
Mit Markdown kann man Text und HTML realisieren.

[1] https://de.wikipedia.org/wiki/Markdown
[2] http://showdownjs.github.io/demo/
[3] https://github.com/Dynalon/mdwiki/releases

[weshalb]

Habe ich das nun richtig verstanden, dass Markdown lediglich meine Files nach einer bestimmten Syntax in Form bringt, ich aber zum Anzeigen, Suchen und Verwalten dieser dann doch andere Programme nutzen muss?

[ThorstenS]

Ja, das ist der große Vorteil.
Du kannst eine MarkDown Datei direkt lesen - also im vim schreiben/lesen.
sphinx,pandoc oder atom( mit entspr. plugins) können dir beim Rendern helfen.

MarkDown ist sowas wie der kleine Bruder von RestructuredText (womit sphinx eigentlich arbeiten mag).

Ich bin ein Consolenmensch, brauche meine doku überall - auch ohne browser oder gar Clientprogramm.
Daher ist der manpage-output von sphinx auch so genial und den epub output hab ich im Calibre und kann ihn auf meine Geräte synchronisieren.

Bei sphinx ist es allerdings ein gewisser Aufwand, bis du alles so eingerichtet hast, wie du es brauchst.
Dokuwiki scheint eine Lösung zu sein, die dich schneller ans Ziel bringt und trotzdem eine enorme Flexibilität bietet - dank MarkDown.


Einfaches Dokument:

Code: Alles auswählen

# Überschrift 1. Ordnung

**fett geschrieben**
* Aufzählung
  * 2. Ordnung
* wieder 1. Ordnung

## Code

```bash
#!/bin/sh
echo "hallo Welt"
```
## Tabelle 
| Nr  | Bezeichnung  |
| --- | --- |
| 01 | Server |
| 02 | Clients |

## Link
[http://link.me](beschreibung)

[uname]

Reines Markdown:
Verwalten kannst du die Inhalte in Ordner und Dateien (datei.md).
Problem sehe ich aktuell in der Suche (leider keine Idee).

Dokuwiki:
Dokuwiki hat eine Suche. Aber auch entsprechend Overhead.
Ich denke Dokuwiki nutzt keine reinen Markdown-Dateien.
Es gibt aber ein "markdowku Plugin".

[weshalb]

Na mir geht es quasi darum, dass ich suchen,meine Dokus miteinander verlinken, auf einer Frontseite eine Übersicht anlegen und sofort verändern kann. So wie bei MediaWiki.

[ThorstenS]

Ok, falls du bei mediawiki bleibst, schau dir mal das Wiki hier an: https://www.thomas-krenn.com/de/wiki/
Die lassen die Navigation links dynamisch über Kategorien erstellen. Das erspart es dir händisch eine vernünftige Verlinkung zu bauen.
Du mußt die Seiten nur „taggen” und sie sind immer über die Navigation links erreichbar - auch mehrfach in unterschiedlichen Kategorien…

Hier siehst du deren Erweiterungen:
https://www.thomas-krenn.com/de/wiki/Spezial:Version

[weshalb]

Danke nochmal für den Link. Auf Krenn stoße ich auch so öfter und finde es gut, wie die dokumentieren.