Official Documentation

[daniel-farina]

I'm starting this issue to track the best way to create the official documentation for Osmosis. Ideally, I think all documentation should live inside a /docs folders inside the main osmosis repo. If you were to clone the repo, all docs are right in there. No dependencies. I believe Tendermint does this with vue-press but we could look into other alternatives.

Recent Updates

First POC is live. We made a fork of the main Osmosis repo for now. We will create a PR once we are close to finalizing the docs branch.

• Fork with documentation lives here https://github.com/osmosis-labs/osmosis/tree/docs inside the docs folder.
• Instructions on how to contribute posted on at bottom. (DOCS_README.md)
• Vuepress was upgraded to 2.x
• A git action was created here: https://github.com/daniel-farina/osmosis/blob/main/.github/workflows/docbuild.yml
• • It builds and deploys the static site to the gh-pages branch
• • This branch can then be used from the repo settings as the default page for the repository.
• • A preview of the site is available here https://osmosis-labs.github.io/osmosis/ every time changes are pushed to the main branch. This will eventually become something like docs.osmosis.zone.

Contributors

@daniel-farina
@czarcas7ic

Todo

• Upgrade to vuepress 2
• Add a custom theme
• Create a git action to auto deploy to gh-pages
• Created a documentation for docs
• Clean up navigation (Remove things that are not longer relevant, simplify navigation, reduce number of categories, expand all categories by default, etc)
• Complete doc's main index
• Add the latest instructions on how to join the main net
• Add the front-end documentation
• Add any other relevant docs from other repos #691
• Add some styling (Check with the front-end team)
• Update all links to point to the relative's doc paths
• Create PR to main Osmosis repo
• Update main osmosis repo's documentation to point to the new docs #693
• [Epic] Add front-end documentation docs#33

@ValarDragon @sunnya97 Please let us know if you have any questions or concern about the proposed documentation site.

We are tracking this documentation effort here:
https://github.com/orgs/osmosis-labs/projects/1/views/10

Thanks!

[daniel-farina]

I started the process of moving ALL known documentation from Gitbooks & and Github into a single Vuepress documentation folder. This will be 100% Markdown living inside a repo (The main Osmosis chain repo for example) which then could be served from docs.osmosis.zone. I created a blank vue-press site from scratch so that the front-end team can customize anyway they wish. This will allow us to have a coherent place where all documentation lives as well as a place for the open source community to make changes via pull requests. I will finish up a concept/poc and then share it with the team to do a review and approval.
This is the same way Tendermint & Cosmos writes documentation. Gitbook is nice but it’s not open source and less community driven. I'll keep this issue updated.

Suggestions are welcomed!

[czarcas7ic]

A lot of our focus is going to be both completing incomplete and/or incorrect documentation as well as splitting technical and non technical knowledge articles as to not overwhelm newcomers. Let us know if you agree with the intent/vision for the product.