From 04de273003b6f346d3a39186fa51ec8d8d96dd0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?benjamin=20melan=C3=A7on?= Date: Fri, 7 Aug 2020 23:52:23 -0400 Subject: [PATCH] update documentation documentation formatting --- documentation.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/documentation.md b/documentation.md index 6396b12..54e2e7a 100644 --- a/documentation.md +++ b/documentation.md @@ -4,12 +4,12 @@ Welcome to the meta section of our documentation where we document how to do doc 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. +```{tip} +This documentation page is a good one to copy or refer to for an example of MyST formatting. And of course anyone can come and clean up formatting later. ``` -Where to post what ------------------- +## 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/)). @@ -17,8 +17,7 @@ Somewhere is better than nowhere. Don't worry about [translation](translation). -Guidelines -++++++++++ +## Guidelines * Document closest to where people work: * In README.md files or otherwise in the code repository for developers. @@ -29,6 +28,7 @@ Guidelines 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. ``` +## Local preview Running this documentation locally: