Document
========

In order for your software package to be useful, documentation is required that
describes how your software can be installed, operated, used and improved:

* Those who want to use your package need information,

  * what problems your software solves and what the main features and
    limitations of the software are (→ :ref:`readme`)
  * how the software can be used as an example
  * what changes have come in more recent software versions (→ :ref:`changelog`)

* Those who want to run the software need an installation guide for your
  software and the required dependencies.

* Those who want to improve the software need information about

  * how to help improve the product with bug fixes (→ :ref:`contributing`)
  * how to report security vulnerabilities (→ :ref:`security`)
  * how to communicate with others (→ :ref:`coc`)

All together need information on how the product is licensed (:file:`LICENSE`
file or :file:`LICENSES` folder, → :ref:`license`) and how to get help if
needed.

.. tip::
   cusy seminars:

   * `Software documentation with Sphinx
     <https://cusy.io/en/our-training-courses/software-documentation-with-sphinx.html>`_
   * `Technical writing
     <https://cusy.io/en/our-training-courses/technical-writing.html>`_

.. 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>`_

.. toctree::
   :titlesonly:
   :hidden:

   sphinx/index
   doctest
   badges
   shot-scraper