Format for group YAML files

[wigging]

The CocoaHeads group is working on an iOS app for KnoxDevs. We are using a JSON file as the database for the mobile app. The YAML files used for the group data can be readily converted to JSON for app development. However, the current YAML format for each group is sparse on details.

name: Knoxville CocoaHeads #Name of organization
image:
online: #Online links
    website: http://knoxcocoa.org
    twitter: 
    meetup: knoxcocoa
location: # Meetup Location
    name: The Technology Cooperative
    gmap: pMBTD5bcBSp # google map short url.
slack_channel: #slack channel most associated with your group.
blurb: CocoaHeads is a group devoted to discussion of Apple's Cocoa and Cocoa Touch Frameworks for programming on OS X and iOS. During monthly meetings, members offer tutorials, present their projects, share app ideas, and provide advice to other programmers. #A blurb (~ 50 words) about your organization goes here!

I would like to propose a YAML format similar to the example given below.

name: Knoxville CocoaHeads

description:
  CocoaHeads is an iOS and macOS developers group in Knoxville, TN. Meetings are
  held on the last Monday of each month from 6:30-8:30pm at the Technology
  Cooperative.

location:
  name: The Technology Cooperative
  address: 13 Emory Place, Knoxville, TN 37917
  latitude: 35.9747
  longitude: -83.922917
  website: http://techco.org

organizers:
  - name: Gavin Wiggins
    twitter: https://twitter.com/wigging
    website: https://gavinw.me
  - name: Bill Morefield
    twitter: https://twitter.com/bmorefield
    website: http://www.billmorefield.com

social:
  email: info@knoxcocoa.org
  facebook: https://www.facebook.com/knoxcocoa
  github: https://github.com/knoxcocoa
  meetup: https://www.meetup.com/knoxcocoa
  twitter: https://twitter.com/knoxcocoa
  website: http://knoxcocoa.org

tags:
  - ios
  - macos
  - swift

[alexpawlowski]

I like part of this suggestion, I propose a compromise:

name: Knoxville CocoaHeads

image: /assets/images/groups/knox_cocoa.webp #cards need an image

description: > # need a `>' to break long string in YAML across multiple lines. (carriage return will become a space
  CocoaHeads is an iOS and macOS developers group in Knoxville, TN. Meetings are
  held on the last Monday of each month from 6:30-8:30pm at the Technology
  Cooperative.

location:
  name: The Technology Cooperative
  address: 13 Emory Place, Knoxville, TN 37917
  latitude: 35.9747
  longitude: -83.922917
  website: http://techco.org

organizers: # I will link to your organizers profile by using anchors, ex. #Gavin+Wiggins
  - Gavin Wiggins
  - Bill Morefield

social:
  facebook: https://www.facebook.com/knoxcocoa
  github: https://github.com/knoxcocoa
  meetup: https://www.meetup.com/knoxcocoa
  twitter: https://twitter.com/knoxcocoa

online:
  email: info@knoxcocoa.org
  website: http://knoxcocoa.org

tags:
  - ios
  - macos
  - swift

slack_channel: 

Items I would like to retain:

• images - each group needs to upload an image to have a nice formatted listing.
• slack_channel - this is the slack channel where most offline discussions happen. Not every group has one, but this helps direct new users to the appropriate channel. On the website, if a group does not have a slack channel, the slack button and channel link will not be displayed.

Elements I like:

• rename blurb to description. Good change, blurb was probably too informal.
• tags. Attributes about the group would be good to have, sets the stage for searching later.
• Organizers. Meant to add something for Organizers.
• adding breaks between each yaml key, makes it more human-readable, which is why yaml was chosen in the first place 👍

Changes to suggestion:

• Because we have data of the organizers, I propose to just have organizers list their name. and remove the key "name". We can get attributes about the organizers from the organizers data section. I propose linking to the organizer's profile under the about page using FirstName+LastName.
• Email and Website is generally not considered to be "social media", it might be weird to new contributors in the future?. so just propose listing those under online.

On the fence about:

• I like Location, but unsure about listing Latitude and Longitude. We could add an API to geocode addresses like listed here. What3Words would be a fun thing to have instead, but that would then force a service. I agree that maybe using the Google Maps short code wasn't the best plan.

Also it seems that more documentation should be placed in the README.

[wigging]

My suggestions for the yaml format are for a more generic approach not just for a Jekyll website. I made a Python script that converts the yaml files into a single json file (I'll post it to the KnoxPy GitHub tonight). So I'm trying to think of a format with fields that work well with json. Although, such an approach may not be ideal for Jekyll. 🤷‍♂️ With that in mind, here are some more comments:

Do you need to have organizers info in a separate yaml file? It's more convenient to have everything about a group in one file. This also reduces entering the same things like group name, organizer name, etc. into different files.

As for location, providing something other than a Google Map link would be good. You can still provide the google link but have options for other things like lat/lon, zip code, address, etc.

[alexpawlowski]

We do need organizers in a separate yaml file. If you look at the about page, we have a listing of organizers. The idea here is that "the organizers" should all be recognized as part of KnoxDevs, as the community is in large part a result of the contributions of the groups themselves. The idea, also, was that organizers may "organize" more than one meetup, so the idea was to minimize duplicate information. Of course, this may be the case of an "edge case" driving the overall work flow, so maybe that isn't the right approach. Also, I'm thinking generally, that you just need a name for the organizers. We could write something that pulls in all of the organizer's info if it's really needed for the api?.

Regards to location. I am pretty sure we can geoencode the location information to build a google maps direction, so that might make the google url redundant anyhow. I agree that using a location service that is platform agnostic, would probably be a better solution. Lat Long isn't perfect, but is probably easier than making an organizer use what3words or similar service to get the location coordinates.

[wigging]

You could create a locations folder that has a yaml file for each meetup location. Then refer to that in the groups yaml files. Similar to how you handle the organizers.

[alexpawlowski]

True. Or just make it so that each place a meetup holds their meetup includes a file for event spaces. Which would probably be true, anyhow.

[alexpawlowski]

Most recent commit takes the suggestions posted here. We can reopen if further ideas come up!