Schreiben
=========

Gut geschriebene Texte ermöglichen es Menschen, unsere Informationen mit
Leichtigkeit zu nutzen. Diese Richtlinien wurden anhand von Beispielen aus der
Praxis entwickelt und richten sich an alle, die für cusy technische
Dokumentationen schreiben.

cusy-Texte sind bestens wenn

* sie schön dargestellt sind
* sie keine impliziten Annahmen treffen
* sie so einfach wie möglich sind
* sie komplex werden können, aber nicht kompliziert
* …

.. seealso::
   * `The Zen of Python <https://www.python.org/dev/peps/pep-0020/>`_
   * `Material Design: Writing <https://material.io/design/communication/writing.html>`_
   * `Google developer documentation style guide <https://developers.google.com/style/>`_
   * `IBM Accessibility: Content design
     <https://www.ibm.com/able/toolkit/design/content/overview/>`_

Themen
------

Kurz
    Strebt kurze und prägnante Textbeiträge an
Fokussiert
    Beschränkt euch in einem Beitrag auf ein Thema. Beiträge, die mehrere Themen
    umfassen, sollten aufgebrochen werden.
Zugänglich
    Verwendet eine möglichst einfache Sprache ohne Fachjargon. Erklärt
    komplizierte Konzepte, indem ihr sie aufschlüsselt.

Verweist zu öffentlich zugänglichen Artikeln um mehr Details zu eurem Thema zu
erhalten oder einen alternativen Zugang zu eurem Thema zu erhalten.

Barrierefrei schreiben
----------------------

Im Abschnitt :doc:`accessibility` findet ihr detaillierte Anleitungen zum
barrierefreien Schreiben, vor allem zu den Themen:

* Textalternativen für Bild- und Audioinhalte
* Fehler und andere Meldungen
* Beschriftungen und Eingaben für Formulare

.. seealso::
   * `Web Content Accessibility Guidelines (WCAG)
     <https://www.w3.org/WAI/standards-guidelines/wcag/>`_

Fragen und Feedback
-------------------

Wenn euch etwas fehlt oder ihr Erläuterungen zu einem bestimmten Anwendungsfall
benötigt, könnt ihr uns gerne Fragen stellen in einer `GitHub-Aufgabe
<https://github.com/cusyio/cusy-design-system/issues>`_.

Einführung
----------

.. toctree::
    :titlesonly:
    :maxdepth: 0

    about

Schlüsselanweisungen
--------------------

.. toctree::
    :titlesonly:
    :maxdepth: 0

    highlights
    wordlist
    voice-tone

Grundlagen
----------

.. toctree::
    :titlesonly:
    :maxdepth: 0

    accessibility
    gender
    writing-style

Verlinkung
----------

.. toctree::
    :titlesonly:
    :maxdepth: 0

    link-text

Computer-Schnittstellen
-----------------------

.. toctree::
    :titlesonly:
    :maxdepth: 0

    api-reference
    code
    placeholder
    ui-elements

Testen
------

.. toctree::
    :titlesonly:
    :maxdepth: 0

    testing