GM Optimism 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 Optimism, 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 Optimism ecosystem.
Key Components of Our Proposal:
Developer Documentation:
Detailed setup guides for development environments
Comprehensive API references
Best practices for building on Optimism
Integration guides with popular frameworks
Performance optimization techniques
Security considerations
SDK and Testing Framework Documentation:
In-depth documentation for all Optimism 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 Optimism-specific terms
Use Case Studies:
Detailed examinations of successful Optimism projects
Insights into architecture and development processes
Regular Maintenance and Updates:
Commitment to keeping all documentation current
Expected Outcomes:
Reduced learning curve for new Optimism developers
Increased efficiency for existing developers
Enhanced understanding of Optimism’s capabilities in the broader blockchain community
Accelerated adoption and integration of Optimism 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.
Kaushik from PYOR, a crypto research company, proposes creating a comprehensive documentation hub for Optimism to enhance the developer experience and foster adoption. The proposal includes developer documentation, SDK guides, interactive learning tools, community resources, use case studies, and regular updates for the documentation. The goal is to reduce the learning curve, increase efficiency, and accelerate the adoption of Optimism in blockchain projects. The plan involves phased implementation with a focus on thorough research, content creation, and ongoing maintenance for valuable resources.
Hey Kaushik (@DODO), thanks for posting about this! My name is Cynthia, and I’m part of the Technic…
Hey Kaushik (@DODO), thanks for posting about this! My name is Cynthia, and I’m part of the Technical Docs team at Optimism Foundation / OP Labs, and these views are my own.
This project aligns with what we’re already trying to do internally currently, which is getting clear understanding of where we currently are with our technical documentation. For example, work is already underway to build out a comprehensive, integrated Technical Content strategy for all our docs touchpoints —docs.optimism.io, specs.optimism.io 1 , and community.optimism.io, public notion+google pages, and github repos (with lots of cool developer tooling few folks know about). I don’t think that we can build a central resource for developers without actually understanding where all of the OP technical content lives and how all of the pieces fit together.
Most of the proposal feedback is organized around these 3 areas: 1 ) project alignment and internal processes, 2 ) documentation critical needs and best practices, and 3 ) community involvement and support.
Project Alignment and Internal Processes
The project aligns with internal efforts to understand and organize existing content, but a project of this scope and complexity will continue to require internal coordination with Optimism’s process changes and future goals.
An example where internal OP coordination is crucial: deprecation of the Optimism SDK and the need to update related documentation (notice page, SDK site deprecation, etc.). Work is already underway to update all SDK tutorials to viem by end of Q 4 , or sooner.
So, this is an example of tooling that we’re not going to continue supporting and doesn’t align with the future trajectory in terms of the Collective’s goals. So an external team would need to be aligned with us on something like this or else we’ll have further fracturing in our docs touchpoints.
We also have a cross-functional team working on an Optimism Glossary (two exist actually, one in specs and one in devdocs), and we are working to combine these efforts and get internal alignment. Next, we’ll pair the integrated glossary with a number of pending docs features (discussed a bit later) to make it more useful/interactive for devs across all docs touchpoints.
Documentation Critical Needs & Best Practices
We want to ensure the focus remains on delivering comprehensive, up-to-date content rather than introducing new tools without addressing core concerns.
The greatest docs need at present are documentation updates or revisions, to stay aligned with the OP Stack code base. There are several issues tagged as good first issue and tutorials that interested documentarians/writers can take on that would be a great help to the OP docs team. But really, teams are welcome to assign themselves to any docs issue 1 to work on!
We also want to follow best practices for docs content, based on research. For example, video content and extensive FAQs are not highly effective for developer documentation based on research. There was even a gov proposal by a group last year to build video content – but unfortunately this content never made it to docs.
We maintain a list of docs feature requests that are addressed, according to priority and bandwidth, with Algolia search as the most recent docs feature integrated. We could really use a helping hand with adding additional docs features, if this proposal team (or others) would like to help in this capacity. The Algolia integration was via bounty, but we are open to missions or other pathways to achieve this goal.
Community Involvement and Support
Tapping into community resources for tutorials, troubleshooting guides, docs revisions, and docs feature enhancements would be most beneficial for the OP Docs team.
We’ve also discussed future plans for a DocsNERDS program to help address docs maintenance (in terms of content revisions tied to code base changes). If you have any thoughts or perspective on what a DocsNERD program could look like, we’d love to hear it! This could be similar to other contribution paths 1 .
Some clarity around which developer groups this proposal/project will support could be really helpful too because we need onboarding documentation for spec docs for our decentralized devs as well. So having an external team help us to write that onboarding documentation for decentralized devs could be helpful.
We’d love to find ways to strategize and build momentum around these specific areas with the proposal authors. This will likely require us to create more structured processes for community members to contribute, but we are up to the task! :heart_decoration:
Going forward, it would also be helpful to get a better sense of your research, migration plans, and execution strategy to have a better understanding of the implications of this project.
Let me know what you think. Thank you for taking the time to propose this idea.
Hey Kaushik (@DODO), thanks for posting about this! My name is Cynthia, and I’m part of the Technic…
Hey Kaushik (@DODO), thanks for posting about this! My name is Cynthia, and I’m part of the Technical Docs team at Optimism Foundation / OP Labs, and these views are my own.
This project aligns with what we’re already trying to do internally currently, which is getting clear understanding of where we currently are with our technical documentation. For example, work is already underway to build out a comprehensive, integrated Technical Content strategy for all our docs touchpoints —docs.optimism.io, specs.optimism.io, and community.optimism.io, public notion+google pages, and github repos (with lots of cool developer tooling few folks know about). I don’t think that we can build a central resource for developers without actually understanding where all of the OP technical content lives and how all of the pieces fit together.
Most of the proposal feedback is organized around these 3 areas: 1 ) project alignment and internal processes, 2 ) documentation critical needs and best practices, and 3 ) community involvement and support.
Project Alignment and Internal Processes
The project aligns with internal efforts to understand and organize existing content, but a project of this scope and complexity will continue to require internal coordination with Optimism’s process changes and future goals.
An example where internal OP coordination is crucial: deprecation of the Optimism SDK and the need to update related documentation (notice page, SDK site deprecation, etc.). Work is already underway to update all SDK tutorials to viem by end of Q 4 , or sooner.
So, this is an example of tooling that we’re not going to continue supporting and doesn’t align with the future trajectory in terms of the Collective’s goals. So an external team would need to be aligned with us on something like this or else we’ll have further fracturing in our docs touchpoints.
We also have a cross-functional team working on an Optimism Glossary (two exist actually, one in specs and one in devdocs), and we are working to combine these efforts and get internal alignment. Next, we’ll pair the integrated glossary with a number of pending docs features (discussed a bit later) to make it more useful/interactive for devs across all docs touchpoints.
Documentation Critical Needs & Best Practices
We want to ensure the focus remains on delivering comprehensive, up-to-date content rather than introducing new tools without addressing core concerns.
The greatest docs need at present are documentation updates or revisions, to stay aligned with the OP Stack code base. There are several issues tagged as good first issue and tutorials that interested documentarians/writers can take on that would be a great help to the OP docs team. But really, teams are welcome to assign themselves to any docs issue to work on!
We also want to follow best practices for docs content, based on research. For example, video content and extensive FAQs are not highly effective for developer documentation based on research. There was even a gov proposal by a group last year to build video content – but unfortunately this content never made it to docs.
We maintain a list of docs feature requests that are addressed, according to priority and bandwidth, with Algolia search as the most recent docs feature integrated. We could really use a helping hand with adding additional docs features, if this proposal team (or others) would like to help in this capacity. The Algolia integration was via bounty, but we are open to missions or other pathways to achieve this goal.
Community Involvement and Support
Tapping into community resources for tutorials, troubleshooting guides, docs revisions, and docs feature enhancements would be most beneficial for the OP Docs team.
We’ve also discussed future plans for a DocsNERDS program to help address docs maintenance (in terms of content revisions tied to code base changes). If you have any thoughts or perspective on what a DocsNERD program could look like, we’d love to hear it! This could be similar to other contribution paths.
Some clarity around which developer groups this proposal/project will support could be really helpful too because we need onboarding documentation for spec docs for our decentralized devs as well. So having an external team help us to write that onboarding documentation for decentralized devs could be helpful.
We’d love to find ways to strategize and build momentum around these specific areas with the proposal authors. This will likely require us to create more structured processes for community members to contribute, but we are up to the task! :heart_decoration:
Going forward, it would also be helpful to get a better sense of your research, migration plans, and execution strategy to have a better understanding of the implications of this project.
Let me know what you think. Thank you for taking the time to propose this idea.
Hey Cynthia,
Thank you for taking the time to provide such detailed feedback! We will discuss inter…
Hey Cynthia,
Thank you for taking the time to provide such detailed feedback! We will discuss internally to ensure our proposal aligns perfectly with the team’s goals and requirements. We’ll get back to you soon with a refined approach.
