Restructure Permaweb Cookbook Around Full-Stack Developer Journey

[dpshade]

Problem Statement

The current Permaweb Cookbook structure lacks clear direction for developers new to the ecosystem. Users struggle to understand how HyperBEAM, AO, Arweave, AR.IO, etc. work together in practice, leading to fragmented adoption and increased support overhead.

Proposed Solution

Restructure the documentation around a "zero-to-deployed-app" walkthrough that demonstrates the modern Permaweb stack in action.

New Navigation Structure

• Getting Started → Full-stack tutorial (raw JS/HTML deployed to Arweave)
• Starter Kits → Framework-specific tutorials (Vite, Svelte, Vue, etc.)
• Core Concepts → Largely stays the same (fundamentals)
• Tooling → GraphQL, bundling, manifests, HTTP API, etc. (clearer purpose)
• References → Largely stays the same (strictly references)
• Community → Ecosystem showcase (partner with wander.apps)
• Legacy → Outdated but potentially useful content

Implementation Plan

Content Audit & Organization

• Identify and move outdated content to Legacy section
• Reorganize existing content into appropriate navigation sections
• Update broken links and references

Core Content Creation

• Write comprehensive Getting Started full-stack tutorial
• Expand Starter Kits with framework-specific guides
• Enhance Community section with ecosystem showcase

Expected Outcomes

• Faster developer onboarding
• Better adoption of full Permaweb stack
• Improved developer experience

Seeking Feedback

@DevChanQ @longviewoor @atticusofsparta

1. Does this restructure align with your vision for Permaweb developer experience?
2. Are there specific sections or content you'd like to see prioritized?
3. Any concerns about moving existing content to Legacy?
4. Any other thoughts?

[longviewoor]

Hi @dpshade, I think this is a great initiative and part of the reason I have been working on PRs for the cookbook.

I agree that there is an issue with how users understand how the pieces fit together, and I think there's also an entry point issue. The cookbook isn't very linear and although jumping around concepts can be useful, it is a little bit confusing.

I think the full-stack journey is a good idea and can directly lead into AO.

I think if I was to start building on Arweave right now, I'd want to know how it works -> how to upload data (and websites) -> how to build on this further with AO Processes (with link to AO cookbook). I think this pretty much aligns with what you're saying 🙂

As for the other points:

• I think we should prioritize updating to the structure you recommended, as well as cleaning up a lot of the existing content.
• I think legacy should be removed entirely as it adds more content to manage and the majority of developers will not need it.
• We shouldn't forget some "edge cases", e.g. people working for existing projects that just want Arweave storage, e.g. Mirror.
• We should be opinionated, and offer a specific development path with tooling in order to avoid confusion.

We can set up some issues and delegate some work between us here @dpshade if you're up for it.

[DevChanQ]

Agreeing with what's mentioned here. I say we go for it

[atticusofsparta]

I would like to take a slightly different perspective on the cookbook.

For starters, we are currently approaching from a developer point of view, and thats great for part of it.

However theres a lot of recipes on arweave and ao that do not require any code whatsoever.

Another big failing I think is news. What updates and events are currently happening? how many nodes are up? whats the status of the chain? What new features were released?

With that in mind, I think we should have a general guides section, with specific easy to use workflows to accomplish certain tasks, a build section for developers who can come and see the cool shit we can do in the guides section and want to build things like it, and a main forum/news section for people to get an idea of what is happening on the permaweb (inclusive of arweave, ao, and even integrations like cross chain bridges). Perhaps a collaboration with arweave hub is in order there.

General no code Workflows

• Creating a wallet, jwk, ecdsa, seed phrase, and info on how accounts in arweave work (eg first transaction has higher gas)
• Uploading data, using AR, or a bundler, with focuses on images, text, pdfs, and websites, with emphasis on also accessing your data on gateways, and using specific apps like arweave.app, ardrive, dragondeploy, bazar, arlink, etc...
• Usage of the UDL (Universal Data License) and legal cases / precedents backing it, and how to apply it to certain materials you upload (ardrive has a licensing integration built in and i think bazar does as well)
• (self plug :P ) Getting a permanent domain name and how to manage it (also in the realm of hosting and accessing data, might be better in the uploading section)
• ... other workflows

Builder centric workflows

• Documentation wide framework/language selection
• Chain selection - eg arbundles. Are you using signers for a fully featured arbundles parity, or just one? arweave, eth, sol?
• • If so, should warn that only arweave and eth are natively supported on AO for example, and others are not recommended (can explain my opinion further there if desired)
• Workflow targeted documentation of features - eg, heres upload, and heres how to use it targeting progress bars, indexing, resolution, manifests, etc. Included in this can be another flag for component libraries we recommend, eg arweave kit, shadcn, radix, tailwind, and so on.
• Cryptographic best practices, e.g encryption and management of keys in development environments.

https://docs.sentry.io/ is a good example of a front page for the docs I would like to see. Allows you to quickly route from framework to what you want to do in the best communication for your specific need.

[dpshade]

I agree with a lot of your ideas here @atticusofsparta. Another direction (larger direction) I think makes sense is a Choose Your Path guide. The landing page could ultimately become a Who are you? or What are you here for? We can identify the primary 4-6 user groups that are visiting, whether they are node operators, builders, defi/traders, general users, investors, etc. Then, based on their chosen persona, we provide a dedicated guide that assumes zero knowledge and gets them up to speed with just the technology relevant to their goals.

[atticusofsparta]

@dpshade agreed, that would allow a more dedicated algo for a "for me" section.

[atticusofsparta]

[dpshade]

Some more refined thoughts on the above:

Core Philosophy

Meet users where they are with dedicated pathways for different archetypes. Each path is siloed and takes users from zero to expert within their specific context.

Proposed User Archetypes

Builder - Static websites, Full-stack applications
Explorer - Data discovery, GraphQL querying, blockchain analysis
Gamer - On-chain gaming, AO-powered games
Quant - DeFi, trading, financial applications
Node Operator/Runner - Running ar.io, Arweave, HyperBEAM nodes
Jack of All Trades - No-code solutions, ArDrive, general data upload

Landing Page Vision

Hero - "Arweave is permanent decentralized storage where you are the owner"
Subheading - "This unlocks far more than you may have realized"
Path selection - Column-based layout with persona descriptions
Optional - Interactive quiz to guide path selection

Supporting Structure

References - Technical specs spanning multiple paths
Community - Ecosystem players, app showcase, developer resources