2.1 KiB
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.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.
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
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 (this private repository automatically publishes non-draft notes publicly to agaric.gitlab.io/raw-notes).
Somewhere is better than nowhere.
Don't worry about 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.
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:
sphinx-build -b html . _build/html