Dokumentieren
=============

Damit euer Software-Paket sinnvoll genutzt werden kann, sind Dokumentationen
erforderlich, die Beschreiben, wie eure Software installiert, betrieben,
genutzt und verbessert werden kann:

* Diejenigen, die euer Paket nutzen wollen, benötigen Informationen,

  * welche Probleme eure Software löst und was die Hauptfunktionen und
    Einschränkungen der Software sind (``README``)
  * wie das Software beispielhaft verwendet werden kann
  * welche Veränderungen in aktuelleren Software-Versionen gekommen sind
    (``CHANGELOG``)

* Diejenigen, die die Software betreiben wollen, benötigen eine
  Installationsanleitung für eure Software und die erforderlichen Abhängigkeiten

* Diejenigen, die die Software verbessern wollen, benötigen Informationen

  * wie sie mit Fehlerbehebungen zur Verbesserung des Produkts beitragen können
    (``CONTRIBUTING``)
  * wie sie mit anderen kommunizieren (``CODE_OF_CONDUCT``) können

Alle gemeinsam benötigen Informationen, wie das Produkt lizenziert ist
(``LICENSE``-Datei oder ``LICENSES``-Ordner) und wie sie bei Bedarf Hilfe
erhalten können.

.. tip::
   cusy Seminare:

   * `Software-Dokumentation mit Sphinx
     <https://cusy.io/de/unsere-schulungsangebote/software-dokumentation-mit-sphinx>`_
   * `Technisches Schreiben
     <https://cusy.io/de/unsere-schulungsangebote/technisches-schreiben>`_

.. seealso::
   * `Eric Holscher: Why You Shouldn’t Use “Markdown” for Documentation
     <https://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/>`_
   * `Tom Johnson: 10 reasons for moving away from DITA
     <https://idratherbewriting.com/2015/01/28/10-reasons-for-moving-away-from-dita/>`_
   * `Tom Johnson: Jekyll versus DITA
     <https://idratherbewriting.com/2015/03/23/new-series-jekyll-versus-dita/>`_
   * `Google developer documentation style guide
     <https://developers.google.com/style/>`_
   * `Google Technical Writing Courses for Engineers
     <https://developers.google.com/tech-writing/overview>`_
   * `Cusy Design System: Schreiben
     <https://www.cusy.design/writing/index.html>`_

.. toctree::
   :titlesonly:
   :hidden:

   sphinx/index
   doctest
   badges
   shot-scraper