diff --git a/documentation.md b/documentation.md new file mode 100644 index 0000000..6396b12 --- /dev/null +++ b/documentation.md @@ -0,0 +1,37 @@ +# 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.md](https://gitlab.com/agaric/documentation/blob/master/documentation.md)). 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) (this private repository automatically publishes non-draft notes publicly to [agaric.gitlab.io/raw-notes](https://agaric.gitlab.io/raw-notes/)). + +Somewhere is better than nowhere. + +Don't worry about [translation](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 [values](values) of encouraging continuous learning, appreciating new ideas, giving back to the communities we are part of, and valuing long-term relationships. +``` + + +Running this documentation locally: + +```bash +sphinx-build -b html . _build/html +``` diff --git a/documentation.rst b/documentation.rst deleted file mode 100644 index be59e7b..0000000 --- a/documentation.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _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 `_ (for example, the edit link on this page takes you to `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 `_: If you're not sure where to put something in documentation, or if it even is documentation, `write a blog post `_. Or even, in the Agaric context, just throw it in a `raw note `_ (a private repository but non-draft notes are published to `agaric.gitlab.io/raw-notes `_). - -Somewhere is better than nowhere. - -Don't worry about `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. - - -Running this documentation locally: - -sphinx-build -b html . _build/html