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 Q4, 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!
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.