RFC-001: Event Data Structure & Storage

[ashleemboyer]

1. Summary

Use Markdown files and YAML Front Matter for describing the group's calendar events and store the files in the website repository.

2. Related Issues / PRs

• Architect Event data structure and storage #4
• Implement Events page #12
• Implement individual Event page #14
• Implement Event RSVP functionality #17

3. Goals

• Create a data structure for describing events held by the group
• Have the ability to add more data properties in the future when needed
• Determine where to store the event data
• Storage needs to be free or very low cost and somewhat scalable
• Have the ability to fetch the data in the website app to show to visitors
• Use a strategy that's approachable for all experience levels

4. Proposal

4a. Data Structure

To start, Events will need to have the following attributes:

• unique id/slug: for use in page URLs, generated by the randomUUID() function
• title: for use in <title>, <h1>, and Open Graph title
  • No hard limit on characters, but we can recommend ~60 in the docs or a template
• start datetime: when the event will start, stored in ISO format
  • Example: May 31, 2024 at 1:30pm ET would be stored as '2024-05-31T17:30:00.000Z'
• duration: how long the event will last, stored as an integer representing minutes
  • Easier to think of than math-ing out the end time
  • Example: 1.5 hours would be stored as 90
• location: a string URL or address (we can use an object later if it turns out easier that way)
• short description: for use in lists of Events and Open Graph description, stored as plain text
  • No hard limit on characters here either, but we can make a recommendation
• full description: for use on each Event's page

4b. Data Storage

Each Event's data will be stored in a single Markdown file within the website repository.

• We can store many files for free in the repo for a long time.
• Co-located content where build scripts run from will yield faster build times since no API calls need to be made to external sources.
• No other applications, accounts, or software will be needed for viewing the data, simplifying its long term maintenance and onboarding new contributors to the project.

All attributes except the full description will be stored in the Markdown file's YAML Front Matter. The full description will be stored in the body of the file. This enables the Event pages to easily have rich text content with links, lists, and multiple paragraphs. These have been used in past Event pages on Meetup.com, so we want to make sure to retain that functionality.

5. Alternatives

1. Relational SQL database vs. static files: in our early versions of the website, we won't have any dynamic data (such as RSVPs) to store. We'll only need to store static, seldomly-changing data. Storing data externally also introduces extra layers of configuration and account access for contributors. We can still opt for this in the long term, but for now it would likely introduce more friction than benefits.
2. JSON vs. Markdown + YAML: JSON would work until we come to the need for rich text content on Event pages. We could write Markdown in a longDescription property in a JSON object, but it's not as easy to do so in comparison to writing it in a Markdown file.

6. Resources & Terms

1. Data serialization: the process of turning a data structure into a format that can be shared, stored, and converted back into its original form.
   a. What is Serialization? | freeCodeCamp
   b. Data Serialization | The Hitchhikers's Guide to Python
   c. Data Serialization | Devopedia
2. Front Matter: a block of YAML at the top of a Markdown file for adding metadata to the document. It originated in Jekyll, a static site generator. Some websites for publishing written content allow authors to customize special variables for articles like title, description, canonical URL, etc.
   a. Front Matter | Jekyll
   b. Using YAML frontmatter | GitHub
   c. Front Matter | DEV Editor Guide
3. Markdown: a markup language that enables plain text with some syntax to be converted into HTML elements. It was created in 2004 by John Gruber.
   a. Markdown | Daring Fireball
   b. What Is Markdown? | Codecademy
   c. MarkdownGuide.org
   d. Markdown Cheat Sheet | freeCodeCamp
4. Open Graph: metadata protocol for turning web pages into objects for sharing in social websites and applications.
   a. The Open Graph protocol
   b. What is Open Graph and how can I use it for my website? | freeCodeCamp
   c. Open Graph and Twitter Images | Next.js
5. YAML: a language for serializing data intended to be "human-friendly" and easier for people to read and write.
   a. YAML.org
   b. What is YAML? The YML File Format | freeCodeCamp
   c. What’s the Difference Between YAML and JSON | AWS

[quinnmcphail]

This looks great! I think the data structure needs a bit more defining to it. For instance: id/slug format, datetime format, title/description length recommendations. Just want to set standards so it's scalable.

[ashleemboyer]

Just added more details to id/slug, title, start datetime, duration, and short description!

[mrzamin]

Great job. I agree that this way of storing the data, instead of storing it in a database, will be easier for onboarding new contributors in the future. I learned something new today -- Open Graph protocol :)