Documentation for OPSI

This is the source of the official documentation for the open source client management solution opsi.

The documentation is published on the website https://docs.opsi.org.

• Documentation for OPSI
  • Edit this documentation
  • How to build an OPSI manual (Antora and HTML/PDF)
  • Accept changes from external
• Sprachführer deutsches Handbuch

Edit this documentation

There are two main ways to edit the documentation:

1. Via the edit link on docs.opsi.org.
2. Fork this repository and clone your copy. Edit the files locally and create a pull request (GitHub).

You need a Github account either way.

In case you are working for UIB, use our internal Gitlab repository.

Edit via docs.opsi.org

You can edit the OPSI documentation directly via [docs.opsi.org] (https://docs.opsi.org) and submit your changes as a pull request on GitHub.

1. Go to [docs.opsi.org] (https://docs.opsi.org) and click Edit this page in the top-right corner of the page you want to edit.

2. You will be redirected to GitHub. You need to sign in with a GitHub account to edit the documentation. After signing in, fork the upstream repository opsi-org/documentation. This creates your own copy of the repository, where you can make your changes.

3. The GitHub editor opens with the selected documentation page. Make your changes and then click Commit changes....

You can make several changes and create several commits before creating the pull request.

4. The dialog "propose changes" opens. Enter a meaningful commit message that briefly describes what you changed.

5. When you changes are complete, create a pull request:

6. The "Open a pull request" page opens. Enter a meaningful title and, optionally, add a description explaining your changes.

A member of the uib staff will review the pull request and, if appropriate, merge the changes into the upstream repository.

How to build an OPSI manual (HTML)

You can build the OPSI documentation in the Visual Studio Code Dev Container. The container provides the tools required to build the Antora site and the HTML/PDF manuals. Prerequisites: Docker installed and running on your system (Windows: Docker Desktop), VS Code, and the Dev Containers (VS Code extension).

Build the Antora site with a VS Code task

1. Open the repository in the Dev Container.

   In VS Code, open the Command Palette with Ctrl+Shift+P and select Dev Containers: Rebuild and Reopen in Container.

   Make sure the lower-left corner displays Dev Container: opsidoc-asciidoctor.

2. Run the build task.

   Open the Command Palette with Ctrl+Shift+P and select:

   Tasks: Run Task → Build Antora site → local-playbook.yml

3. Open the generated site.

   After the build completes, the terminal displays a message similar to:

   Open file:///workspaces/opsidoc/build/site/index.html in a browser to view your site
   

   Open the generated index.html file in your browser. Replace workspaces with the path to your local repository, for example:

   file:///home/alice/code/opsidoc/build/site/index.html
   

Troubleshooting container creation

If the post-create.sh script fails while creating the container, run it manually from the VS Code terminal:

 `./.devcontainer/post-create.sh` 

Check, if the ui/bundle exists

If there is a directory antora-ui/build and it contains a file named ui-bundle.zip proceed to the next section of this README. Otherwise, create the bundle with

cd antora-ui
gulp bundle
cd ..

Create Antora site without the VS Code task

To create the Antora site with your local changes execute:

npx antora --log-level=debug local-playbook.yml

Accept changes from external

Changes made through docs.opsi.org require the contributor to open a pull request on GitHub: github.com/opsi-org/documentation.

Questions and discussions can take place in the pull request on GitHub.

Sprachführer deutsches Handbuch

Ein gutes Handbuch

• vermittelt Wissen,
• ist sprachlich-formal korrekt,
• hat einen für Fachliteratur passenden Stil,
• ist klar und verständlich.

Die Leser sollen nachvollziehen und verstehen können, was zu tun ist. Komplexe Sachverhalte werden Schritt für Schritt vermittelt. Lieber kurze Sätze als lange Sätze. Wir nutzen die direkte persönliche Leseransprache („Sie“). Das Handbuch vermeidet unnötige Anglizismen und Denglisch: „hochladen“ statt „uploaden“, „herunterladen“ statt „downloaden“ usw. Wiederkehrende Fachausdrücke werden einheitlich geschrieben.

Rechtschreibung

Wir nutzen die neue Rechtschreibung, wie sie im Duden (28. Auflage, 2020) verzeichnet ist. Manchmal bietet der Duden zwei Schreibweisen an: die neue, reformierte Schreibweise und die früher gültige Schreibweise als Alternative. Im Zweifelsfall folgen wir der Empfehlung des Dudens.

cSpell

Für die Rechtschreibprüfung der Dokumentation wird CSpell verwendet. Die Konfiguration befindet sich in der Datei cspell.json. Darüber hinaus gibt es eine Liste von Schreibweisen/Eigennamen im Verzeichnis opsidoc/cspell, die fortlaufend aktualisiert wird. CSpell ist in den VS Code Dev Container integriert und wird automatisch verwendet.

Es besteht die Möglichkeit, Wörter bei der Rechtschreibprüfung zu ignorieren. Hierfür verwendet man direkt in der Dokumentation Kommentare in der Form:

// cSpell:ignore <Wort1>,<Wort2>

Diese Kommentare sollten möglichst in der Nähe des zu ignorierenden Begriffs eingefügt werden.

CSpell kann auch abschnittsweise deaktiviert werden. Das An- und Abschalten erfolgt über Kommentare in der folgenden Form:

// cSpell:disable
[source,toml]
----
[groups]
fileadmingroup = "opsifileadmins"
----
// cSpell:enable

Kommasetzung

Gleichrangige Teilsätze, die durch „und“, „oder“ usw. verbunden sind, setzen ein Komma, um die Gliederung deutlicher zu machen:

• Klicken Sie auf die Schaltfläche OK, und die Installation beginnt.

Auch bei Infinitiv- und Partizip-Sätzen setzen wir ein Komma:

• Klicken Sie auf die Schaltfläche mit den drei Linien, um das Menü zu öffnen.

• Um die Inventarisierung zu starten, klicken Sie auf den Button OK.

• Darauf aufmerksam gemacht, hat der Hersteller das Produkt vom Markt genommen.

Zusammengesetzte Begriffe (DE/EN)

Deutsch-englische Komposita nutzen einen Bindestrich:

• Kernel-Quellen
• Windows-Client (Linux-Client, macOS-Client)
• Windows-basiert
• Linux-kompatibel

Ein Bindestrich wird außerdem gesetzt, wenn zusammengesetzte Wörter sehr lang sind und dadurch schwer zu lesen sind:

• Mehrbenutzer-System
• Software-Inventarisierung

Fachbegriffe/Fremdwörter

Fremdwörter sollten nur dann verwendet werden, wenn es keine passende deutsche Alternative gibt oder wenn es sich um einen feststehenden Fachbegriff handelt.

Es ist ok, "Button" anstelle von "Schaltfläche" und vice versa zu verwenden.

Englische Begriffe, die ins deutsche Handbuch übernommen werden, unterliegen den Regeln der deutschen Sprache:

• Substantive werden großgeschrieben: Loglevel, Debuglevel
• Genitiv von Fachbegriffen wird wie im Deutschen üblich mit „-s“ gebildet: des Clients, des Internets
• auch die Pluralbildung ist wie im Deutschen: Repositorys (nicht Repositories), Floppys (nicht Floppies) usw.
• zusammengesetzte Begriffe, die aus einem oder mehreren fremdsprachigen Wörtern und mindestens einem deutschen Wort bestehen, werden zusammengeschrieben bzw. mit Bindestrich: das Support-Paket, das Client-Management, die Software-Inventarisierung

Eigennamen

Unsere Software heißt OPSI (alles Großbuchstaben), und der Begriff wird genau so geschrieben.

Maßeinheiten

Maßeinheiten werden wie im Duden geschrieben; es gibt kein Plural-s:

• Byte
• MByte
• GByte
• TByte

Zwischen einer Zahl und der Maßeinheit steht ein nicht-trennbares Leerzeichen ({nbsp}):

2{nbsp}GByte, 300{nbsp}GByte usw.

Das sieht dann so aus: 2 GByte, 300 GByte usw.

Auflistungen

Es gibt nur einen einzigen Grund, nummerierte Aufzählungen zu verwenden: wenn es auf die Reihenfolge ankommt.

1. Klicken Sie auf die Schaltfläche Installieren.
2. Ein neuer Dialog öffnet sich; klicken Sie dort auf OK.

Alle anderen Auflistungen sind nicht nummeriert. Bei Auflistungen von Features oder Funktionen sollten die einzelnen Punkte möglichst einheitlich gestaltet sein (entweder ganze Sätze oder nicht, entweder mit Großbuchstaben beginnen oder nicht).

Typografie

Ein nicht-trennbares ({nbsp}) Leerzeichen steht an folgenden Stellen:

• Abkürzungen z. B. (zwischen z. und B.), o. Ä., d. h.
• zwischen Ziffern und Maßeinheiten: 3 GByte, 64 Bit
• zwischen Auslassungspunkten … und dem vorangegangenen Wort: „Möglich ist das …“

Es gibt keinen Leerraum vor und nach einem Schrägstrich (DIN 5008): RHEL/AlmaLinux/Rocky Linux

Farbige Kästen

Zur Auflockerung und zum Sichtbarmachen wichtiger Informationen nutzen wir die folgenden farbigen Kästen:

NOTE: Das hier ist eine Anmerkung, sie wird hinter NOTE: gesetzt

TIP: Das hier ist ein Tipp, er steht hinter TIP:

WARNING: Hier steht eine Warnung, sie steht hinter WARNING: (Achtung: Wir haben uns entschieden, nur WARNING und nicht auch noch CAUTION zu verwenden!)

Schreibweisen und Hervorhebungen

Wir verwenden in diesem Handbuch die folgenden Schreibweisen und Hervorhebungen:

Proportionalschrift (monospace)

In asciidoc werden Backticks (`) verwendet um Text in Proportionalschrift darzustellen. Proportionalschrift wird zur Hervorhebung der folgenden Elemente verwendet:

• Datei- und Verzeichnisnamen:
  • Die Host-ID ist in der Datei /etc/opsi/opsi.conf hinterlegt.
• Befehle im Fließtext:
  • Führen Sie den Befehl apt update aus.
• Befehls-Parameter:
  • Über den Parameter --debug schalten Sie in den Debug-Modus.
• Text der in Felder oder Dateien eingegeben wird:
  • Geben Sie den Wert true ein.
  • Fügen Sie die Zeile opsi-server 10.1.2.3 am Ende der Datei ein.
• Kurze Befehls-Ausgaben:
  • Die Ausgabe Version 4.3.0.1 erscheint.

Kursive Schrift

Um etwas kursiv zu formatieren, wird in asciidoc der Unterstrich verwendet (_Wort_). Kursiv erscheinen die folgenden Elemente:

• Menüeinträge und Beschriftungen von Schaltflächen und Eingabefeldern:
  • Klicken Sie auf den Button OK.
  • Öffnen Sie das Menü Datei / Speichern unter.
  • Tragen Sie den Namen des Rechners ins Feld Hostname ein.

Fettgedruckte Schrift

In asciidoc werden Sternchen (*) verwendet um Text fett darzustellen. Fettgedruckte Schrift wird zur Hervorhebung der folgenden Elemente verwendet:

• Eigennamen:
  • OPSI bietet mit dem OPSI-configed ein komfortables Management Interface.

Code-Blöcke und Listings

Längere Befehle, Code-Auszüge und Auszüge aus Dateien stehen in eigenen Kästen. Diese Listings besitzen den folgenden Aufbau:

.Optionaler Titel
[source,<Typ>]
----
<text>
----

Gültige Typen sind beispielweise: console, shell, bash, ini, xml, html, css.

Achtung: Es gibt einen Unterschied zwischen [source,console] und [source,shell]:

• [source,console] stellt Text dar, das in eine Konole (also eine Terminalanwendung) eingegeben wird
• [source,shell] ist für Inhalte von Shellskripten (Alternative: [source,bash], [source,zsh])

Weitere Konventionen

• In <spitzen Klammern> stehen Bezeichnungen, die Sie durch ihre Bedeutung ersetzen müssen. So heißt die Dateifreigabe mit den OPSI-Paketen z. B. <opsi-depot-share>. Auf einem realen Server liegt sie in der Regel in /var/lib/opsi/depot. Das Softwarepaket <opsi-depot-share>/ooffice befindet sich also unter /var/lib/opsi/depot/ooffice.

• Tasten und Tastenkombinationen stehen in eckigen Klammern, z. B. [C], [Strg]+[C] usw., normaler Font (keine Proportionalschrift)

• In Überschriften werden keine Texthervorhebungen verwendet.