documentation/documentation.rst

.. _documentation:

Documentation
=============

Welcome to the meta section of our documentation where we document how to do documentation!

Edit or add.  That's the primary instruction.  You can edit directly on `gitlab.com/agaric/documentation <https://gitlab.com/agaric/documentation>`_ (for example, the edit link on this page takes you to `gitlab.com/agaric/documentation/blob/master/documentation.rst <https://gitlab.com/agaric/documentation/blob/master/documentation.rst>`_).  If you aren't a member of Agaric, GitLab will helpfully offer to fork the documentation to your own namespace so that you can make a merge request with your documentation suggestion.

.. note::
    This documentation page is a good one to copy or refer to as an example for ReStructuredText formatting.  And of course anyone can come and clean up formatting later.


Where to post what
------------------

We like `Gitlab's approach <https://about.gitlab.com/handbook/git-page-update/#where-should-content-go>`_: If you're not sure where to put something in documentation, or if it even is documentation, `write a blog post <https://agaric.com/node/add/blog>`_.  Or even, in the Agaric context, just throw it in a `raw note <https://gitlab.com/agaric/resources/raw-notes>`_ (a private repository but non-draft notes are published to `agaric.gitlab.io/raw-notes <https://agaric.gitlab.io/raw-notes/>`_).

Somewhere is better than nowhere.

Don't worry about `translation <translation>`_ or :ref:`translation`

Guidelines
++++++++++

* Document closest to where people work:
   * In README.md files or otherwise in the code repository for developers.
   * In the site itself for site managers and content editors, or alternatively in an organization's already established locations.
* Topics which are of general application can be abstracted, put in this repository, and linked to at this documentation.

.. note::
    In doing documentation we are living our :ref:`values` of encouraging continuous learning, appreciating new ideas, giving back to the communities we are part of, and valuing long-term relationships.