Improving Docs
Current problems
Quick starts
- They're too long, especially the Write Data From Your App. Many start with "Create an account", "create a secret", "authenticate", "create a project" -- boring! Makes you want to skip the whole thing. It hides the "meat" of each tutorial.
- There are several ways to do each action (write data, read data), so it feels wrong to show the user just one way, and not give them context about the other ways
- Sharing data shouldn't be in a quick start. That'll never be someone's first activity with Beneath.
Other
- "Reading & Writing Data" section mixes the two concerns
- Need to take out the CLI instructions and replace with Console "Create Resource" buttons
- We'll need to build up the users understanding from the basics (write one record to Beneath) to the advanced (write continuously with a Pipeline)
- Pipelines: need to explain Python generators and yield syntax
- Need a Hello World kind of Pipeline example (Ethereum blocks has too many complexities)
Ideas
- New structure: Introduction, Getting Started, Writing Data, Reading Data, Pipelines, Sharing Data, more...
- Create Resource buttons that we can put in about.beneath.dev. First you're directed to log-in if necessary, then you're redirected to the Create page that you expected.
Edited by Eric Green