Comprehensive Osmosis Documentation Hub

Proposal Discussion
1

GM Osmosis Community,

I’m Kaushik from PYOR, a crypto research and analytics company backed by Coinbase Ventures and Castle Island Ventures. We leverage on-chain data to address critical business questions for institutional investors and protocols.

Given our extensive experience in the blockchain space, we propose creating an all-encompassing documentation hub for Osmosis, serving as a central resource for developers, community members, and newcomers. Our vision is to significantly enhance the developer experience, accelerate onboarding, and foster broader adoption of the Osmosis ecosystem.

Key Components of Our Proposal:

Developer Documentation:

Detailed setup guides for development environments
Comprehensive API references
Best practices for building on Osmosis
Integration guides with popular frameworks
Performance optimization techniques
Security considerations
SDK and Testing Framework Documentation:

In-depth documentation for all Osmosis SDKs
Guides on setting up and using testing frameworks
Best practices for writing and running tests
Interactive Learning Tools:

Step-by-step tutorials for building various application types
Video guides complementing written content
Code sandboxes for hands-on learning
Interactive quizzes to test understanding
Community Resources:

Comprehensive FAQs
Troubleshooting guides
Glossary of Osmosis-specific terms
Use Case Studies:

Detailed examinations of successful Osmosis projects
Insights into architecture and development processes
Regular Maintenance and Updates:

Commitment to keeping all documentation current
Expected Outcomes:

Reduced learning curve for new Osmosis developers
Increased efficiency for existing developers
Enhanced understanding of Osmosis capabilities in the broader blockchain community
Accelerated adoption and integration of Osmosis in various projects
Strengthened community support through accessible resources
Our approach involves a phased implementation, starting with thorough research and planning, followed by content creation, review, and refinement. We’re committed to ongoing maintenance to ensure the documentation remains up-to-date and valuable.

We would be excited to discuss this proposal further and provide any additional information you might need.

2

Can you provide a sample / demo page?
I mean, pick some page from the existing docs, explain why it needs improvement (or just describe something crucial which is missing entirely I guess) then create a page for it.

How do you plan to research? What do you plan to research?

Do you have experience with cosmos sdk/tendermint/wasm development? Are there any similar chains you’ve done this for in the past?

2 Likes
3

Thanks for this one @maxpower !

A Proof-of-Concept to show what @dodo can bring is a great idea.

4

Hey @maxpower, thank you for your feedback and questions. We appreciate the opportunity to clarify our proposal and demonstrate our approach. Here’s our detailed response:

We’ve identified that the “Validating and running the node” page has a crucial area for improvement. Here’s why:

The way we identified this is that while working on retrieving data from the Osmosis Archive for our PYOR project, we encountered firsthand the challenges developers face we attempted to set up an Osmosis node using Quick Sync, but faced data reliability issues. This led to delays in our development process and highlighted the need for more robust documentation.

Some of the challenges are:

  1. Lack of Reliability with Quick Sync for Node Creation:

The current page lacks detailed troubleshooting steps and alternative methods for node setup, which can lead to developer frustration and delays.

We found that developers rely heavily on third-party services like Quick Sync for setting up nodes. The main issue here is the lack of confidence in the reliability of the data. Developers are uncertain whether the provided data will function correctly, which can delay the development process and create trust issues.

Some of the common problems that developers are talking about which we can see here:

  1. Fallback Steps in Cosmovisor Usage

The documentation lacks clear fallback procedures for errors when using Cosmovisor for the Cosmos ecosystem. This has caused confusion, particularly among developers when something goes wrong. By improving this section, we can ensure developers are better equipped to handle potential issues, making their experience smoother and less frustrating.

Our goal would be to address this by providing more transparent and reliable documentation about these third-party integrations the way we plan to resolve these issues:

Cosmovisor Documentation Enhancement

  1. Comprehensive Cosmovisor Guide: We will provide a complete guide covering the entire lifecycle of using Cosmovisor with Osmosis.
  2. Purpose & Benefits: Clear explanation of Cosmovisor’s purpose and its benefits for Osmosis node operators.
  3. Step-by-Step Setup: A detailed walkthrough of the setup process, ensuring smooth implementation.
  4. Best Practices: Include best practices for using Cosmovisor in different environments (development, testnet, mainnet).
  5. Effective Upgrades: Guide on how to handle upgrades efficiently and minimize issues.
  6. Troubleshooting: A robust troubleshooting section to address common issues developers face.

Manual Node Setup Guide Proposal

  1. In-Depth Manual Setup Guide: We will create a detailed guide for manual node setup to complement the existing wizard documentation.
  2. Step-by-Step Explanations: Provide comprehensive explanations for each step in the manual setup process, clarifying the purpose behind different configuration options.
  3. Wizard vs. Manual Comparison: Include a comparison between wizard and manual setups to help users choose the best method based on their needs.
  4. Informed Decision-Making: Equip users with the knowledge to select the most suitable setup process for their specific requirements.

Efficient Data Download and Integration Proposal

  1. Advanced Download Utilities: Propose integrating more efficient download methods, such as multi-threaded downloads, resume capability, and better error handling, into the Osmosis setup process.

  2. Alternative Download Methods: Document various download options, explaining their benefits and how they can improve the setup process for node operators.

  3. Improved Setup Reliability: Provide node operators with tools to reduce initial setup time and enhance data acquisition reliability.

  4. Seamless Integration: Show how to integrate these methods with the existing Osmosis setup for a smoother, more efficient experience.

  5. Additional Enhancements for Osmosis Development

We propose to enhance the existing Osmosis node setup wizard to accommodate Cosmovisor based setup. Especially for full-archive node setups involving snapshot syncs from third-parties like “quicksync.io”.

  1. Our team has extensive experience in blockchain development and distributed systems. We’ve worked with protocols focused on data modules and dashboards, and have closely studied the Cosmos ecosystem, including Tendermint and WASM. Additionally, we have collaborated with ATOM Accelerator to build a web front-end for the Partial Set Security (PSS) Economic Model. We’ve also developed internal plans for future work on Cosmos SDK projects and are currently seeking further clarification to proceed.

GitHub Repo.
Frontend for PSS

  1. Research Plan

Our research approach includes:

  • Hands-on testing of all node setup methods
  • Surveying the Osmosis developer community for pain points
  • Analyzing GitHub issues and forum discussions
  • Comparing Osmosis documentation with other Cosmos ecosystem projects

We hope the above answers provide additional clarity to our proposal and the commitment to deliver high-quality documentation to the Osmosis team.

5

I’m a little unclear on exactly what the proposal is asking for here.

We do have a documentation hub:

which is a public github repo:

This could almost certainly do with an overhaul and being updated, if nothing else by bringing the more developer facing github readmes into it and revisiting some of the older pages which haven’t been updated in a while.

Commits are very welcome here, but a secondary documentation site seems like it would just cause confusion due to conflicting information rather than having one main place that was updated.

1 Like
6

Thank you for your feedback @JohnnyWyles. After internal discussions, we fully agree that creating a separate documentation site would be redundant and potentially confusing. Instead, we propose to focus our efforts on enhancing the existing documentation at docs.osmosis.zone.

As outlined in our previous message, we’ve identified specific areas for improvement and proposed comprehensive solutions to address these issues. These enhancements aim to resolve our challenges, such as reliability concerns with Quick Sync and unclear procedures for Cosmovisor usage.

We aim to enhance the existing Osmosis documentation, creating a comprehensive resource for all developers. Before proposing a budget for this initiative, we want to assess its feasibility. We will await further feedback before finalizing the scope of work.

7

Yeah this is not a bad idea, it’s something I had wanted to do at one point but it’s quite a large task.

Also:

This covers the node setup and better download methods -

This covers Cosmovisor (although typically I wouldn’t suggest anyone even use Cosmovisor for any reason but to set up an archive node) -

8

Osmosis Developer Doc Enhancement x PYOR

The final document has been updated according to feedback from @maxpower and @JohnnyWyles on the Node setup documentation improvements

Objectives and deliverables

The primary goal of this proposal is to enhance the existing “Validating and Running the Node” documentation, ensuring it meets the needs of developers and node operators within the Osmosis ecosystem. The specific objectives are:

  • Enhance the existing page with comprehensive troubleshooting guides for Quick Sync and Cosmovisor.
  • Provide clear, reliable alternatives for node setup,(provided official snapshot data file from Osmosis team), reducing reliance on third-party services with uncertain data reliability.
  • Develop an in-depth manual node setup guide to complement the existing wizard-based documentation.
  • Include step-by-step explanations and compare wizard and manual setups to allow developers to choose the best method.
  • Create a complete lifecycle guide for ‘using Cosmovisor with Osmosis’, covering installation, upgrades, and troubleshooting.
  • Provide best practices for using Cosmovisor across different environments (development, testnet, mainnet) to prevent common errors and improve setup reliability.

The following 6 pages will be added to the current documentation to achieve the above:

  1. Process of running osmosis node, Hardware requirements, and Summary
  2. Preparing the server and all the necessary installations
  3. Step-by-step process to setup an Osmosis node with Quicksync and Cosomoviser
  4. Step-by-step process to set an Osmosis node with Polcachu setup provider
  5. Docker-based Setup Using Docker containers to run an Osmosis node
  6. Solution to frequently occurring problems and FAQs

These 6 pages are directly integrated into GitHub - osmosis-labs/docs: Official Documentation for Osmosis. by raising a PR.

Before integration, we will perform QA checks with the Osmosis Devrel team as well as a community developer-based focused group.

Budget

Category Amount (USD) Percentage Description
Research and Planning $1,500 15% Analyze existing docs, identify gaps, plan new structure
Content Creation $4,000 40% Write 6 new pages, develop guides, create instructions
Technical Implementation $2,000 20% Set up test environments, verify procedures, ensure accuracy
Quality Assurance $1,500 15% Internal review, community testing, incorporate feedback
Integration and Finalization $1,000 10% Prepare PR, collaborate with the Osmosis team, and make final adjustments

Timeline:

  • 1st November - 31st November

About PYOR:

At PYOR, we enhance blockchain protocols, DAOs, and dApps with targeted research and analytics. We work with protocols like Arbitrum, Cosmos, and Compound. We’re backed by industry leaders including Castle Island Ventures and Coinbase Ventures, etc.

Past Work:

9

Can you still provide a Proof-of-Concept to get an idea of the deliverable we will get?

In essence I never have heard someone complain about lacking the tools to start a node on Osmosis, so I really doubting the need for this to be honest.

I also do think that documentation will still need some level of technicallity, since running a node on Osmosis is not the easiest node to run. Other chains are simply easier to start with. In the end it is important to have quality nodes on Osmosis due to the demand the chain has on the nodes itself and the hardware it runs on. Some basic understanding of Linux commands and such is also very much a pre before starting to run a serious node.

1 Like
10

With what Max shared, it seems like all of this information is available and just needs customizing to Osmosis and a PR making.

Updating the node setup guides doesn’t feel like a month and $10k worth of work.

The wizards also cover most user needs. Spending on manual setup documentation doesn’t seem like a value add here.

11

Hey @JohnnyWyles , @LeonoorsCryptoman ,

Thank you for your detailed feedback on our proposal. We greatly appreciate the time you’ve taken to review our suggestion and provide your insights.

Based on your response, we understand that the Osmosis team has been working internally on documentation improvements and that our proposed scope may not align with your current needs or priorities.

In the future though we would love to explore more opportunities again.

We look forward to staying connected with the Osmosis community.