ethereum-optimism / docs

Optimism Developer Docs
https://docs.optimism.io
74 stars 127 forks source link

[DOCS] Simplify docs to clarify key concepts #655

Open joohhnnn opened 2 months ago

joohhnnn commented 2 months ago

Brief Description of the Docs Request

The request is to simplify the complexity of documentation on the website, with an emphasis on highlighting broad concepts through easily understandable visual and textual examples. The goal is to make the docs more accessible, especially for those without a development background.

Description of the Documentation You'd Like

Just like a normal learning path, you start with the big concepts, like from the official documentation. Then, I might go to places like SPECS to understand deeper mechanisms. Official docs could link to these places, but it’s probably best to avoid getting too bogged down in the nitty-gritty details.

Additional Context

Many users, particularly those without a technical background, find current documentation overwhelming due to its complexity and technical depth. By reorganizing the documentation to prioritize clarity and accessibility, and by providing clear links to more detailed content, we can improve the user experience. This approach not only aids in quicker comprehension but also encourages further exploration into more detailed aspects as needed, making the docs more effective and user-friendly.

sbvegan commented 2 months ago

Thank you @joohhnnn for the feedback and I agree this would be a nice improvement to the fault proof overview page :)

sbvegan commented 2 months ago

As you mentioned in our chat, this Peek a live code-walkthrough of the new OP Stack fault proof code! video is helpful