29 lines
1.6 KiB
ReStructuredText
29 lines
1.6 KiB
ReStructuredText
.. _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>`.
|
|
|
|
Somewhere is better than nowhere.
|
|
|
|
Principles
|
|
----------
|
|
|
|
* Document closest to where people work:
|
|
* In README.md files or otherwise in the code repository for developers, .
|
|
* Abstract and link here
|
|
|
|
.. note::
|
|
In documentation we are living our `values <values>` of encouraging continuous learning, appreciating new ideas, giving back to the communities we are part of, and valuing long-term relationships.
|