When we give examples in our documentation, we want them to tell a story about building one kind of project. This lets us be more creative/engaging. We should avoid making the entire guides a linear tutorial, and we should avoid tying the Guides content directly to an example app. Each topic should be readable as a stand-alone example. However, reusing the same resource types and explanation context for our code examples will help lower the mental overhead for new learners.
Here's an example with a breakdown of how various aspects of an app could help us teach Cardstack.
project name:
PostCards
Event:
It’s a photo contest! Submit a photo, and the top 6 submissions receive a set of postcards that have the winners.
Problem space examples:
- Top level card - something that contains the whole "app"
- Cards - each photo submission is an instance of a card (?)
- Authentication - users must register
- Persisting and Relating data - photos are associated with users, so the winner can be contacted
- Saving form data - registration and form submission
- Using existing Cards - the dev does not need to make their own photo taking/uploading functionality. They can use a pre-made Card!
- Using a plugin (s3 file storage of the photo)
- Metadata - approving uploads and marking winners (?)
- Embedded Display - using routing and templates to show a gallery
- Isolated Display - showing how a card can be displayed on its own
- Animation - switch between embedded & isolated views
- Four edges - editing the data about the photo submission
- Server side CPs - has this user reached the submission limit?
Resource types
- User - has contact info that is not publicly visible, and a username that is
- Photo - has the file id to use with S3, description, title, date, owned by a User
- File - cache of S3 data?
- Rating - owned by a contest facilitator, relationship to a photo. Has a score, category, and notes. (category is so we can show enum)
- Contest - deadline, per user limit
Learning curve
Most examples should lean on user/photo/file explanations. Maybe also Contest? Mods & ratings should be saved for more advanced topics/cookbooks.
When we give examples in our documentation, we want them to tell a story about building one kind of project. This lets us be more creative/engaging. We should avoid making the entire guides a linear tutorial, and we should avoid tying the Guides content directly to an example app. Each topic should be readable as a stand-alone example. However, reusing the same resource types and explanation context for our code examples will help lower the mental overhead for new learners.
Here's an example with a breakdown of how various aspects of an app could help us teach Cardstack.
project name:
PostCards
Event:
It’s a photo contest! Submit a photo, and the top 6 submissions receive a set of postcards that have the winners.
Problem space examples:
Resource types
Learning curve
Most examples should lean on user/photo/file explanations. Maybe also Contest? Mods & ratings should be saved for more advanced topics/cookbooks.