.. _about_docs:

About the Docs
==============

This is a short guide that aims to help you get the most from the documentation.
Documentation is grouped first by what kind of user you are, then by what kind of
information you are after.

The Many Kind of User
---------------------

What you want to know will be affected by how you use :code:`stylo`, a core contributor
will want to know different information from a user who is using :code:`stylo` for the
first time. Documentation on this site is mostly written with one of the following types
of user in mind.

User
^^^^
A user is anyone who takes what is provided by the :code:`stylo` package and uses it to
create images. They are not looking to build on it in anyway. If this is you then head
on over to the :ref:`use`.

Extender
^^^^^^^^
This is a more advanced user, they are looking to take some of the tools and objects
that are a part of :code:`stylo` and extend them in some way. For example they could be
looking to write custom :code:`Shape` and :code:`Domain` objects either for their own
personal use or to develop a 3rd party package for others. Guides on how to do this and
more can be found in the :ref:`extend` section.

Contributor
^^^^^^^^^^^

This is anyone looking to contribute to :code:`stylo` itself whether that is by writing
more documentation, adding a new feature or just generally helping out with the project.
If you'd like to get involved then head over to the :ref:`contribute` section for more
details.

.. note::

   If you have better terms for the groups outlined above I'd love to hear them :)

The Four Kinds of Documentation
-------------------------------

Once you have found the section of the site that is relevant to you, documentation is
broken down further by what kind of information you are after. Different kinds of
information is best presented in a certain style.

Here is a brief breakdown of the main styles in use on this site. But be sure to refer
to this `article`_ as it does a better job at explaining this than I could.

Tutorials
^^^^^^^^^

.. todo::

   Link to the various tutorials.

Tutorials act as introductions to ideas and concepts, e.g. you want to create an image
but don't know where to start. They won't tell you everything and they'll mostly focus
on the how, but it should be enough to get you started and point you in the right
direction when you want to know more.

Examples
^^^^^^^^

.. todo::

   Link to the example section.

Examples (called "How To Guides" in the `article`_) demonstrate the usage of various
features in order to realise some specific result such as using the :code:`Rotation`
to rotate some domain. They will assume that you already know the basics of
working with the features shown as little explanation will be offered. Examples are all
about the end result.

Background
^^^^^^^^^^

.. todo::

   Link to the mathematics section.

Background documentation (referred to as "Explanations" in the `article`_) is written
with the aim of deepening your knowledge on a particular topic. This is to provide extra
context as to why certain decisions were made or how a particular feature is implemented.
Since :code:`stylo` builds on a number of mathematical concepts, you will mostly find
articles introducing them here.

Reference
^^^^^^^^^

.. todo::

   Link to the various reference sections.

Reference documentation is where you go to find out the answers to "What ...?" questions
for example

- What are the arguments to :code:`method_x`?
- What is the name of that domain transform again?
- What do I need to do to save an image?

This style of documentation is for when you already understand the concepts involved and
you know what you need to do but need to look up specific details.

.. _article: https://www.divio.com/blog/documentation/


