Berufliche Dokumentationsysteme für Anleitungen? Was setzt ihr ein?

CommanderZed

CommanderZed

OpenBSD User
Teammitglied
Moin,

es geht mir hier nicht um so IP, Credential, Assettdokumentationsysteme - da sind wir relativ gut versorgt, sondern um Systeme wo man strukturiert Anleitungen und ähnliche Informationen für IT-Kollegen sammelt.

Leider hat sich hier bei meinen Arbeitgeber "wildwuchs" über die Jahre eingestellt - es gibt ein Doku-Wiki, es gibt eine Flat-File-Ordnerstruktursammlung auf nen Share, es gibt Anleitungen die mal per Mail oder Newseintrag verschickt worden und nur noch in den Mailarchiven vorhanden sind und natürlich noch die persönlichen Flat-File-Strukturen all meiner Kollegen - mal als Word, mal als Access-Datenbank, mal als PDF.

Wir überlegen uns da mal etwas moderner zu organisieren und ich finde per Googeln ist das super unübersichtlich deshalb mal meine Frage: Was nutzt ihr im Alltag?

Hier ein paar Rahmenbedinungen bei uns:

-> Sollte auch von nur so oberflächlich-it-leuten bedient werden können, also kein git, cvs, cli oder sowas (Think Projektmanager oder so)
-> Muss nicht umsonst sein, soll aber auch nicht absurd viel kosten
-> Für so ca. 10 Mitarbeiter
-> Es sollte möglich sein auch andere Dokumente wie PDFs usw zu integrieren.
 
Ich kann mich der Frage nur anschließen. Bisher hat jedes System, dass wir für die Dokumentation eingeführt haben, um das ganze zu vereinfachen/vereinheitlichen dazu geführt, das wir jetzt ein System mehr haben und es noch uneinheitlicher wurde..
 
Ich weiß ja nicht welche Nebenbedingungen ihr an die Dokumente habt, aber
meine Meinung zu dem Thema (und ich habe schon einige Ansätze gesehen)

Dateisystem mit Ordnerstruktur.

Dokuwiki kann seine Stärken nur ausspielen, wenn es jemand mit Metadaten pflegt. Andere Datenbanksysteme sind noch schlimmer. Und du brauchst jemanden, der das administriert und die Dateien einpflegt.
Bei einem Dateisystem legst du mit Standardmitteln fest wer Schreibrechte (darf Dokumente einstellen) und Leserechte in Ordner hat. Das Einstellen von Dateien passiert durch die Leute mit der nötigen Berechtigung ohne großen Aufwand. Aus Erfahrung ein wichtiger Faktor, daß auch aktuelle Dokumente zeitnah zur Verfügung stehen.
Deinen Mitarbeitern steht der ganze Zoo an hochwertigen Datei Tools (grep , find, ...) zur Verfügung. Ich habe mir dann für meine oft gebrauchten Dokumente eine persönlcihe HTML Seite (also datei.html) auf meinem Desktop gemacht, die Schnellzugriff auf für die mich oft gebrauchten Dokumente ermoglicht. Mit Links kannst du auch unterschiedliche Ordner Zusammenstellungen machen, die auf eine Datei zugreifen (z.B. alle Dokumente für das Projekt xy). Und Backup geht auch ganz normal mit Backup Tools. Mit ein bisschen Scripting kannst du auch HTML Seiten erstellen mit den Dateien ausgehend von der Ordnerstruktur (z.B. Datenblätter-Elektronik/Vishay/Opto/Liste_mit_Bausteinen).
Die Einsortierungsarbeit hast du immer, egal welches Tool
 
serie300 schrieb:
Dokuwiki kann seine Stärken nur ausspielen, wenn es jemand mit Metadaten pflegt. Andere Datenbanksysteme sind noch schlimmer. Und du brauchst jemanden, der das administriert und die Dateien einpflegt.
Bei einem Dateisystem legst du mit Standardmitteln fest wer Schreibrechte (darf Dokumente einstellen) und Leserechte in Ordner hat. Das Einstellen von Dateien passiert durch die Leute mit der nötigen Berechtigung ohne großen Aufwand. Aus Erfahrung ein wichtiger Faktor, daß auch aktuelle Dokumente zeitnah zur Verfügung stehen.
Deinen Mitarbeitern steht der ganze Zoo an hochwertigen Datei Tools (grep , find, ...) zur Verfügung. Ich habe mir dann für meine oft gebrauchten Dokumente eine persönlcihe HTML Seite (also datei.html) auf meinem Desktop gemacht, die Schnellzugriff auf für die mich oft gebrauchten Dokumente ermoglicht. Mit Links kannst du auch unterschiedliche Ordner Zusammenstellungen machen, die auf eine Datei zugreifen (z.B. alle Dokumente für das Projekt xy). Und Backup geht auch ganz normal mit Backup Tools. Mit ein bisschen Scripting kannst du auch HTML Seiten erstellen mit den Dateien ausgehend von der Ordnerstruktur (z.B. Datenblätter-Elektronik/Vishay/Opto/Liste_mit_Bausteinen).
Die Einsortierungsarbeit hast du immer, egal welches Tool
Zum Vergrößern anklicken....

Ich sollte hier erwähnen das ich der einzige bei uns bin der so hochwertige Tools wie grep und find nutzt, es ist eine Windows-Only umgebung und meine Kollegen können nur Word, Excel und Co leider

Denke "gut strukturierte flat-file-folder-struktur" wäre auf jedenfall in meiner engeren Wahl wenn ich mit bsd/linux & co leuten unterwegs wäre.
TBF - das liegt auf sonner Sharepoint Dateiablage und ist dadurch zumindest recht gut mit diesen Standardtools durchsuchbar

Aber linken zwischen den Dokumenten wird dadurch leider zum Glücksspiel, sobald jemand was umbenennt oder das irgendwie anders in seinen explorer Verfügbar macht ist das essig
 
Ganz ehrlich: Ich nutze Forgejo (also ein GIT) um strukturierte und immer gleich aussehende Markdown für die unterschiedlichen Systeme zu verwalten.
Allles ist offfen, EINFACH, nachvollziehbar und revisionssicher abgelegt. Dazu sie passenden Berechtigungen und fertig ist die Laube.
 
CommanderZed schrieb:
es geht mir hier nicht um so IP, Credential, Assettdokumentationsysteme - da sind wir relativ gut versorgt, sondern um Systeme wo man strukturiert Anleitungen und ähnliche Informationen für IT-Kollegen sammelt.
Zum Vergrößern anklicken....

Hallo Zed,

Ich betreue ein paar Vereine und kleinere Firmen und ich habe mir diese Frage auch schon oft gestellt. Schlussendlich habe ich für mich diese Möglichkeiten ausfindig gemacht:

Persönlich: Sphinx[1] oder Docusaurus[2]

* Ich würde alles in Git speichern und über Sphinx daraus eine statische HTML Seite erstellen. Das kann man in einen Container speichern oder direkt lokal auf dem Rechner nutzen.

Verein: BookStack[3] oder Outline[4]

* Das hat den Vorteil, dass die Leute direkt online auf einer Webseite den Inhalt erstellen können.

Firma: XWiki[5] und phpMyFAQ[6]

  • XWiki hat eine grosse Anzahl an Plugins und kann eigentlich mit jedem System eine Verbindung herstellen (z.B. Jira)
  • phpMyFAQ ist eine klassische FAQ

[1] https://www.sphinx-doc.org
[2] https://docusaurus.io
[3] https://www.bookstackapp.com
[4] https://www.getoutline.com
[5] https://www.xwiki.org
[6] https://www.phpmyfaq.de
 
Ich habe das alles in einer oder mehreren Seafile Bibliotheken als PDF gesammelt.
Einfach, simpel und mit jedem Browser zu erreichen, wenn der Client mal bocken sollte.

Ganz kritische Infos gibt es nochmal gesondert an passenden Stellen als .txt, damit man das schnell und problemlos von der Konsole lesen kann.

Kein Word, kein Excel oder sonstwelche kryptischen Formate, in denen mal der eine oder mal der andere versehentlich was reinschreibt oder rauslöscht oder durch ein Update was nicht mehr lesbar oder sonstwie zerschossen wird.

Ist allerdings alles Arbeit und funktioniert vermutlich nur, wenn einer das für alle umsetzt. Sonst herrscht da ganz schnell Chaos.
 
Bei uns gibt es eine Redaktion für öffentliche Dokumente (Handbücher etc.). Die copy-pasten was wir ihnen liefern und bereiten das redaktionell auf (Formatieren, Farben, Übersetzung und Standardphrasen). Wir können über das Ergebnis noch mal drüber sehen und Fehler melden. Was wir selber verwenden ist da vollkommen egal, weil die eh alles neu machen.

Wir haben ein komplexes document lifecycle management in das wir wird Dokumente einpflegen. Das ist quasi eine Dokumentdatenbank mit Versionierung.
Das Problem an dem System, die Versionierung funktioniert schlecht und es gibt keine Struktur. Es ist wirklich schwer Dokumente wiederzufinden. Und wenn man eine neue Version hochladen will muss man das alte Dokument auschecken und die neue Version committen (in der Zwischenzeit kann niemand anderes daran arbeiten). Dafür muss man aber Berechtigungen haben. Also werden viele Dokumente geforkt, was es noch schwerer macht die aktuelle Version zu finden.

Entsprechend hat es sich eingebürgert alles in Markdown direkt im Code repo zu dokumentieren und das Document Life Cycle Management zu ignorieren.
Wenn die Redaktion etwas braucht copy-pastet man das gerenderte Markdown in ein Word Dokument und hängt das an eine E-Mail.
 
Ich bin gerade dabei Obsidian für diesen Zweck einzuführen. Die Gründe für mich sind:
  • Einfaches Markdown ist überall nutzbar
  • Filebasiert, damit steckt das Zeug nicht in einer Insellösung
  • schnelle Suche, Tagging, etc.
  • kann gut per git verwaltet werden
  • mit einem Klick PDFs erzeugen
  • interne Links, also wie ein Wiki verwendbar
  • Files können mit Eigenschaften versehen werden, was interessante Möglichkeiten schafft
  • mit plugins brutal erweiterbar
  • bezahlbar (Kommerzielle Lizenz)
  • ....

Es gibt aber natürlich auch einige Nachteile
  • Kein OpenSource, falls das stört
  • PDFs kann man nicht so einfach "hübsch" machen (ich hätte z.B. gerne einen individuellen Kopf und Fuß, das ist etwas nervig)
  • Kann zwar eingebettete Bilder (z.B. per D&D), aber die Verwaltung der Bilder ist in meinen Augen sehr sperrig
  • Man ist schon etwas eingeschränkt in der Gestaltung im Vergleich zu einer vollwertigen Textverarbeitung o.Ä.
  • ....
 
Nextcloud mit OnlyOffice könnte man sich mal anschauen… da sich eh alle gerade Gedanken um Unabhängigkeit von BigTech machen, taucht die Kombi auch immer wieder in der Presse auf, als alternative zu Office365 mit Sharepoint.
 
SierraX schrieb:
Nextcloud mit OnlyOffice könnte man sich mal anschauen… da sich eh alle gerade Gedanken um Unabhängigkeit von BigTech machen, taucht die Kombi auch immer wieder in der Presse auf, als alternative zu Office365 mit Sharepoint.
Zum Vergrößern anklicken....
Es geht nur um unsere interne Dokumentation einer kleinen Sub-Sub-IT-Abteilung eines europäischen Konzerns der für seine 35000 Mitarbeiter sich recht unabrückbar für Microsoft mit O365 und allem Elend das da sonst so zugehört entschieden hat.

Wir können im kleinen Rahmen, z.B. für unsere interne Organisation eigene Wege gehen, was wir immer dann machen wenn wir sehr gute belastbare Gründe haben, aber das wir von Microsoft, SAP, IBM AS/400, Fortinet, Crowdstrike und wie das ganze Elend sich sonst so nennt Konzernweit wegrücken ist von mir aber auch meiner direkten Führung genauso weit weg wie ... keine Ahnung der Mercedes-Bandarbeiter vom Konzernchef :D :D :D

/edit
Meine IT-Kollegen sind auch leider nicht gaaaaaaaanz so OpenSource freundlich fürchte ich.
Ansonsten vielen Dank an alle bis hierher, ich schau mir einige der genannten Lösungen gerade in Ruhe an, nichts davon hat Eile aber die hinweise waren durchaus hilfreich.
 
Wenn man auf der Dateisystemebene bleiben will, habe ich auch schon mit dem Johnny Decimal-System gute Erfahrungen gemacht. Das funktioniert dann im Prinip aehnlich eines Systems in der Bibliothek (die mit den Buechern). :-)
 
Hab auch schon alles ausprobiert, am Ende ist es aber Confluence geworden und bei Aufgabenplanung JIRA aus dem gleichen Unternehmen.
Leider Cloud Anwendung, Kostenpflichtig und ein US Anbieter.

Mit passender Struktur lassen sich dort ganze Handbücher erstellen und als PDF wie ein Buch exportieren.
Durch Plugins lassen sich auch Tools, wie Visio ersetzen.
Natürlich teilweise gegen Einwurf von Münzen.
 
Ich glaube hier hat jedes Unternehmen einen gewissen Wildwuchs.

Bei uns gibt es Confluence und Sharepoint wo allgemeine Projektdokumente abgelegt werden, Siemens Polarion für Anforderungsmanagement, Anforderungsdokumente und Schnittstellendokumente, Jira für Tickets und bei mir im Team noch einen in Gitlab Pages publizierten Docusaurus wo wir in Markdown geschriebene Architekturdokumentation und unsere Anleitungen ablegen.

Während ich die Arbeit mit Docusaurus sehr angenehm finde, weil es am Ende einfach arbeiten mit Markdown und Git ist halte ich es für die Nutzergruppe die du beschreibst nicht für das geeifnete Tool.

Das bringt mich eigentlich zu meinem Hauptpunkt: Sowohl in meinem jetzigen Job als auch in meinen alten Jobs hatten wir immer recht unübersichtliche Toollandschaften für Dokumentation. Vermeiden lässt sich das auch nur mit viel Disziplin. Viel wichtiger ist meiner Erfahrung nach der Prozess drumherum und gerade bei 10 Leuten muss man die nicht mal aufwändig gestalten. Es reicht ja schon wenn jemand dafür ganz klar und offiziell den Hut auf hat das zu strukturieren und den anderen in den Arsch zu treten mitzumachen und sich an die strukturellen Rahmenbedingungen zu halten.
 
Du musst dich einloggen oder registrieren, um hier zu antworten.
Zurück
Oben