Decide on what the example app is and put it in a styleguide

[jenweber]

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.

[jenweber]

[christse]

I think the scope and technique mapping looks good. As far as the overall card composition strategy, I suggest going with something that will allow for a clear reason for reuse of cards from the public catalog. In this case, reuse the user card (which provides a standard login form and address access control) and ballot card (which can manage scarcity internally). Focus the Contest as the top-level app/card, Entry as the user-contribution wrapper that can be embedded and isolated, and Photo to show how to interact with Hub plug-ins. Countdown card is fun. We need to decide whether Countdown takes the date time field from the Contest or the other way around. Serves different purposes from an instruction point of view.

[jenweber]

Grants example:

{
  type: 'grants',
  id: 'test-grant',
  relationships: {
  who: {
    data: { 
      { type: 'fields', id: 'owner' }
   },
  types: { data: { type: 'cards', id: 'photo-card'}}
    }
  },
  attributes: {
    'may-update': true
  }
}

Realms example:

realms: {groups/%40cardstack%2Fhub,groups/everyone,groups/everyone}