Webbasierte Dokumentation

Du suchst ein Programm für einen bestimmten Zweck?
Benutzeravatar
weshalb
Beiträge: 580
Registriert: 16.05.2012 14:19:49

Webbasierte Dokumentation

Beitrag von weshalb » 14.02.2017 01:59:56

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
Beiträge: 1128
Registriert: 10.05.2008 11:23:50

Re: Webbasierte Dokumentation

Beitrag von eggy » 14.02.2017 06:33:49

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.

Benutzeravatar
Dogge
Beiträge: 1796
Registriert: 13.09.2010 11:07:33
Lizenz eigener Beiträge: MIT Lizenz

Re: Webbasierte Dokumentation

Beitrag von Dogge » 14.02.2017 08:16:25

Debian Testing + Gnome | Linux-Anfänger seit 04/2003
http://files.mdosch.de/2014-07/0xE13D657D.asc

r4pt0r
Beiträge: 1121
Registriert: 30.04.2007 13:32:44
Lizenz eigener Beiträge: MIT Lizenz

Re: Webbasierte Dokumentation

Beitrag von r4pt0r » 14.02.2017 09:34:27

https://readthedocs.org/

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

Benutzeravatar
Lord_Carlos
Beiträge: 3507
Registriert: 30.04.2006 17:58:52
Lizenz eigener Beiträge: GNU Free Documentation License
Wohnort: Dänemark

Re: Webbasierte Dokumentation

Beitrag von Lord_Carlos » 14.02.2017 09:53:51

Also sowas wie Google Docs zum selber hosten?

Code: Alles auswählen

╔═╗┬ ┬┌─┐┌┬┐┌─┐┌┬┐╔╦╗
╚═╗└┬┘└─┐ │ ├┤ │││ ║║
╚═╝ ┴ └─┘ ┴ └─┘┴ ┴═╩╝ rockt das Forum!

Benutzeravatar
hikaru
Beiträge: 9005
Registriert: 09.04.2008 12:48:59

Re: Webbasierte Dokumentation

Beitrag von hikaru » 14.02.2017 10:07:46


Benutzeravatar
weshalb
Beiträge: 580
Registriert: 16.05.2012 14:19:49

Re: Webbasierte Dokumentation

Beitrag von weshalb » 14.02.2017 11:04:12

r4pt0r hat geschrieben: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.

Benutzeravatar
weshalb
Beiträge: 580
Registriert: 16.05.2012 14:19:49

Re: Webbasierte Dokumentation

Beitrag von weshalb » 18.03.2017 01:58:11

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
Beiträge: 1121
Registriert: 30.04.2007 13:32:44
Lizenz eigener Beiträge: MIT Lizenz

Re: Webbasierte Dokumentation

Beitrag von r4pt0r » 20.03.2017 10:11:36

weshalb hat geschrieben: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
Beiträge: 8887
Registriert: 03.06.2008 09:33:02

Re: Webbasierte Dokumentation

Beitrag von uname » 20.03.2017 11:45:55

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.

Benutzeravatar
weshalb
Beiträge: 580
Registriert: 16.05.2012 14:19:49

Re: Webbasierte Dokumentation

Beitrag von weshalb » 20.03.2017 22:23:02

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.

Benutzeravatar
ThorstenS
Beiträge: 2689
Registriert: 24.04.2004 15:33:31

Re: Webbasierte Dokumentation

Beitrag von ThorstenS » 21.03.2017 08:07:15

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: Debianpython-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.

Debianpandoc kann dir mediawiki-syntax nach markdown konvertieren :wink:

uname
Beiträge: 8887
Registriert: 03.06.2008 09:33:02

Re: Webbasierte Dokumentation

Beitrag von uname » 21.03.2017 10:19:52

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

Benutzeravatar
weshalb
Beiträge: 580
Registriert: 16.05.2012 14:19:49

Re: Webbasierte Dokumentation

Beitrag von weshalb » 21.03.2017 12:46:35

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?

Benutzeravatar
ThorstenS
Beiträge: 2689
Registriert: 24.04.2004 15:33:31

Re: Webbasierte Dokumentation

Beitrag von ThorstenS » 21.03.2017 13:34:58

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)


Antworten