Webbasierte Dokumentation

Du suchst ein Programm für einen bestimmten Zweck?
Antworten
Benutzeravatar
weshalb
Beiträge: 1265
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: 3331
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: 1895
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: 1237
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: 5578
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
Moderator
Beiträge: 13559
Registriert: 09.04.2008 12:48:59

Re: Webbasierte Dokumentation

Beitrag von hikaru » 14.02.2017 10:07:46


Benutzeravatar
weshalb
Beiträge: 1265
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: 1265
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: 1237
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: 12043
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: 1265
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: 2875
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: 12043
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: 1265
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: 2875
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)


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

Re: Webbasierte Dokumentation

Beitrag von uname » 21.03.2017 13:38:24

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".

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

Re: Webbasierte Dokumentation

Beitrag von weshalb » 21.03.2017 17:05:12

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.

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

Re: Webbasierte Dokumentation

Beitrag von ThorstenS » 21.03.2017 17:50:21

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

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

Re: Webbasierte Dokumentation

Beitrag von weshalb » 22.03.2017 19:55:17

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

Antworten