Mitarbeiten an dtdocs

Diese Seite beinhaltet die Gestaltungsrichtlinien für dtdocs und Informationen, wie an diesem Projekt mitgemacht werden kann.

Sie wird in das Benutzerhandbuch eingefügt, damit du sehen kannst, wie die Seite zusammengestellt wird und wie es geschrieben wird. Bitte gehe zu GitHub, um die Quelle für diese Seite zu sehen.

Die Struktur der Anleitung und der Inhalt wurden nach den folgenden Kriterien sorgfältig ausgewählt:

  1. Die Anleitung soll umfassend sein, d.h. sie sollte in darktable enthaltenen Funktionalität vollständig beschreiben.
  2. Sie sollte eine konsistente und logische Struktur haben und jeder Teil der Funktionalität soll seinen eigenen logischen Platz in dieser Struktur haben.
  3. Sie soll so lang wie nötig, aber so kurz wie möglich sein: Kürze ist ein Muss.
  4. Sie soll objektiv sein.
  5. Funktionalität sollen nur einmal erklärt werden (mit Ausnahme des grundsätzlichen Anleitung zum Arbeitsablauf in der Einführung).
  6. Bilder sollten nur verwendet werden, wenn dies der besseren Verständlichkeit der wesentlichen Prinzipien dient. Bilder sollten keinen Text enthalten, außer es ist unvermeidbar.

Wir sind grundsätzlich nicht interessiert an:

  1. Das Handbuch zu restrukturieren
  2. Markup Sprachen zu wechseln
  3. Detaillierte Tutorials zum Arbeitsablauf (obwohl wir interessiert daran sind, solche in Blogs entweder auf dartable.org oder pixls.us zu publizieren

Wir sind interessiert an

  1. Rechtschreibungs- und Grammatik-Korrekturen
  2. Klärungen des Textes
  3. Dokumentationen zu neuen Möglichkeiten

Wir sind stark daran interessiert, zu hören, welche Abschnitte der Anleitung keinen Sinn ergeben und warum, sodass wir die Dokumentation verbessern können.

Generell, falls du größere Änderungen machen möchtest, dann eröffne ein Ticket und diskutiere es zuerst mit den Betreuern, um zu verhindern, dass Arbeiten gemacht werden, die dann nicht akzeptiert werden.

🔗Format

Diese Webseite wird in reinem Markdown mit einigen Erweiterungen geschrieben. Sie ist ursprünglich zur Verwendung mit Hugo SSG gestaltet worden. Eine Portablilität ist intendiert, sodass die Seite einfach mit einer anderen Anwendung prozessiert werden kann, falls notwendig.

Dateien sollten in UTF-8 gerendert werden und keine Spaltenumbrüche enthalten.

🔗Struktur

Als Folge wird die Struktur an einem Beispiel eines Hauptkapitels mit Unterkapiteln in der dtdocs Webseite gezeigt.

Beispiel-Kapitel
 _index.md
 Abschnitt1-mit-Unterabschnitten/
 Abschnitt1/
 Bild.png
 _index.md
 Unterabschnitt1.md
 Unterabschnitt2.md
 Abschnitt2.md
 Abschnitt3.md

Einige Notizen zur obigen Struktur:

  • _index.md enthalten keinen Inhalt (sie enthalten nur Metadaten) und werden gebraucht um Abschnitts-Titel mit ToC Einträgen zu verbinden. Im obigen Beispiel definiert example-chapter/_index.md den titel des Beispiel-Kapitels und die Reihenfolge in welcher es im Haupt-Inhaltsverzeichnis erscheint. Gleichermaßen definiert example-chapter/section1-with-subsections/_index.md Metadaten für den ersten Abschnitt des Kapitels.

  • Media-Dateien sollten in einem Verzeichnis mit dem gleichen Namen, wie die Seite haben, auf die sie Bezug nehmen. In diesem Beispiel, example-chapter/section1-with-subsections/subsection1 enthält die Media, die zur Seite subsection1.md gehören.

🔗Metadaten

Metadaten von den Markdown Dateien sind am Kopf der Seite mit yaml präsentiert. Alle Metadaten sollen definiert werden – Die Abschnitte der Modul-Referenzen enthalten eine große Anzahl spezifischer Metadaten – aber das folgende definiert einige minimale Metadaten für die Beispiel-Seite example-chapter/section1-with-subsections/subsection1.md.

---
title: Sub Section 1 Title
id: subsection1
weight: 10
---
title
Dieser sollte den bearbeiteten Titel deiner Seite enthalten. Um einen Doppelpunkt in einen Titel zu integrieren, setze den Titel in Anführungszeichen.
id
Das ist die ID, die gebraucht wird, dass Hugo die Seite identifizieren kann. Sie sollte normalerweise den gleichen Namen haben wie die Datei (für Inhalt-Dateien) oder des Eltern-Verzeichnisses (für _index.md Dateien).
weight
Das ist ein optionales Metadatenfeld, das gebraucht wird, um die Reihenfolge im Inhaltsverzeichnis zu definieren. Falls das Feld weight nicht inbegriffen ist, werden die Seiten in alphabetischer Reihenfolge oder Standardreihenfolge zusammengestellt. Zum Beispiel, um die Abschnitte und Unterabschnitte des obigen Beispiels in umgekehrter Reihenfolge zu definieren, müssten die folgenden Metadaten gesetzt werden:
   example-chapter/
 section1-with-subsections/
 _index.md  # weight: 30 (place section1 page at the end of example-chapter)
 subsection1.md  # weight: 20 (place subsection1 page at the end of section1)
 subsection2.md  # weight: 10 (place subsection2 page at the start of section1)
 section2.md  # weight: 20 (place section2 in the middle of example-chapter)
 section3.md  # weight: 10 (place section3 at the start of example-chapter)

🔗Inhalt

🔗Generelle Anhaltspunkte für den Stil

  • Alle Inhalte sollen in klarem Markdown ohne Shortcodes geschrieben werden und HTML soll auf ein absolutes Minimum begrenzt werden, falls HTML überhaupt benutzt wird

  • Minimalismus ist ein absolutes Muss. Weniger Worte sind vorzuziehen

  • Markdown-Dateien sollen so kurz wie möglich sein

  • Folge den Namensgebungs- und Kapitelaustattungs-Normen aus GUI der Anwendung – namentlich sollen alle Kopfzeilen und Titel in Kleinbuchstaben sein außer den obersten Kapitel-Namen (gilt für die Version in Englisch)

  • Kopfzeilen in einer Datei sollten den Level drei (###) nicht übersteigen

  • Die Führungssprache ist Englisch

  • Gehe davon aus, dass der Leser die Anwendung geöffnet hat, wenn er die Anleitung liest und setze nur dort Bilder ein, wo diese zur Erklärung einer komplexen Funktionalität beitragen

  • Nutze Bild-Textboxen, falls du ein Bild kommentieren musst (z.B. markiere Teile des Bildes mit einem Buchstaben oder einer Zahl und erkläre die Bedeutung in Text, der dem Bild folgt). Platziere keine Worte direkt im bild für Anmerkungen, da dies die genaue Lokalisierung schwierig macht. Siehe diese Seite als Beispiel.

  • Änderungen zum Inhalt sollten mit einem Pull Request oder einem ähnlichen Mechanismus vorgeschlagen werden

  • Deine Beiträge werden lektoriert – nimm es nicht persönlich

🔗Definitionslisten

Die Standard-Methode, um Informationen über darktable-Modul-Einstellungen zu präsentieren, ist der Gebrauch von Definitions-Listen.

GUI Kontroll-Name
Eine Deklaration, von dem, was die Einstellung macht. Zum Beispiel “Setze die Belichtung in EV Einheiten”.

Du kannst so viele Paragrafen einschließen, wie du willst, aber versuche es auf 2 oder 3 zu limitieren.

active-icon eine Einstellmöglichkeit, die mit einem Icon angewählt werden kann
Wenn eine Einstellmöglichkeit mit einem Icon angewählt wird, dann nehme einen Screenshot des Icons im Standard darktable Theme, und setze es eine vor dem Namen der Einstellung
GUI Combobox Name
Comboboxes haben oft mehrere Optionen, die alle angezeigt werden müssen mit separaten Definitionen. Nutze eine Liste mit Aufzählungszeichen mit Kursiv für die Werte der Combobox.
  • der erste Wert: Was bedeutet der erste Wert
  • der zweite Wert: Was bedeutet der zweite Wert

Definitionslisten werden auch während des gesamten Dokumentes gebraucht, wo immer ein Stück Funktionalität definiert werden muss. Siehe zum Beispiel, darktable-cli.

🔗Notizen

Falls du eine wichtige Notiz für den Nutzer präsentieren willst, dann nutze das folgende Format:

Beachte: Das ist eine wichtige Notiz.

🔗Fixierte Fonts-Abstände und Codeblocks

Fixe Abstände für Fonts (mit dem ` Zeichen) sollten normalerweise nur für Codeblocks verwendet werden für Referenzen auf Dateinamen oder Kommandolinien-Parameter.

Interne Links müssen relativ zur jetzigen Datei sein und müssen auf eine gültige Markdown-Datei (.md) zielen. Starte Links entweder mit ./ um das jetzige Verzeichnis oder ../, um auf das übergeordnete Verzeichnis zu repräsentieren.

🔗Bilder

Bei Screenshots der aus darktable Anwendung nutze das Standard-Theme von darktable.

Mehrere Dateinamen-Endungen können dazu benutzt werden, wie Bilder dargestellt werden.

Icon
Um ein Bild als Icon einzusetzen, schließe #icon nach dem Bildnamen in den Link ein: Die Markdown ![squirrel icon](./contributing/contributing.png#icon) gibt den folgenden Output: squirrel icon
Bild Breite
You can set the image width to 25, 33, 50, 66, 75 or 100 per cent of the rendered page width by including #wxx after the image name in the link, where xx is the desired width. For example:
![squirrel](./contributing/squirrel.png#w25) outputs
squirrel
![squirrel](./contributing/squirrel.png#w75) outputs
squirrel
Inline
Mit der Ausnahme von Icons werden Bilder als standesmäßig als Block-Elemente eingebunden. Du kannst das aufheben mit dem Term #inline nach dem Bilder-Namen. Das kann kombiniert werden mit der Breite wie folgt.
![squirrel](./contributing/squirrel.png#w25#inline) ergibt die Ausgabe squirrel
Standard
Standardmäßig werden Bilder als Block mit 100% Breite dargestellt. So ![squirrel](./contributing/squirrel.png#w100) und ![squirrel](./contributing/squirrel.png) sind äquivalent und geben beide das folgende aus:
squirrel

translations