docs: Lint documentation for consistency

[meg-gutshall]

Is there an existing issue for this?

• I have searched the existing issues

Context for documentation change

I've noticed inconsistent terminology throughout our documentation. This is certainly to be expected in projects with multiple contributors!

For example, one of our volunteer positions is referred to as: notetaker, note taker, and note-taker at varying points in this repository – and that's without taking capitalization into account. Another example is our how we refer to our Tuesday/Thursday Coffee meetings. It varies between coffees, coffee chats, Tuesday/Thursday Coffees, among other miscellaneous terms.

We should develop a style guide to pair with the CONTRIBUTING.md file as well as a glossary of terminology. I know there's currently a glossary on the website, but it may be more prudent to move it to this repo for ease of editing and discoverability.

Proposed solution

This will be a bit of a larger lift overall, so I propose breaking it up into sub-issues.

1. Go through the repo and make a list of terminology we'll need to standardize and include in the glossary. We can start the list from the linked discussion below.
2. Replace each term with the standardized version. If we again stall on coming to a consensus, we should at least pick something and homogenize them so they'll be easier to replace later once a decision is made.
3. Move the glossary from the website to this repo.

Resources that can help

I started a discussion to Revisit Our Naming Conventions for Volunteer Roles, however, it grew stale quite quickly and hasn't resulted in any actionable decisions despite my attempts to revive it.

This is the glossary I referenced that's currently hosted on the website.

Collaborators

I'll definitely need input from @adiati98 as Documentation Lead. I think @BekahHW will also want to weigh in on how we decide to standardize our documentation terminology. I'm going to tag @dominicduffin1, @tkshill, and @danieltott in case they have opinions to share.

Code of Conduct

• I've read the Code of Conduct and understand my responsibilities as a member of the Virtual Coffee community

[adiati98]

I totally agree with keeping consistency across our docs, this includes the Resources page on our website.

Let me break down my thoughts here:

• Roles terminology

  I'm leaning towards using capitalization when we refer to a role. For example, Host, MC, Room Leader, Notetaker, etc.

• VC terminology

  • We can refer Tuesday/Thursday Coffees to only Coffees, assuming that our members already familiar with this terms and know what it means. I believe we use Tuesday/Thursday at the beginning to clarify this to our newly members that are not familiar with our terms yet.
  • As for Coffee chat, I think it depends on the sentence if we need to clarify it with chat or we can go only with Coffee. So, I'm okay with both ways.
  • Using capitalization for Coffee will give clarification that we're talking about our weekly Coffees.

• Style guide

  We use Docusaurus for this repo, and the syntax and all is quite different. Therefore, I also had a thought that in one point, we want to have some sort of Style Guide to help folks contribute to this repo.

  I've helped develop OpenSauced's intro repo contributing guidelines for this matter. We might want to adopt this guide for our repo, either as a whole contributing guidelines or only take the Working with Content and Using Markdown for this Project sections, and modify based on our needs.

  I can work on this in the near future. @BekahHW, do you have any thoughts on this?

• Glossary

  My thoughts when creating the Glossary for our Resources on VCIO was to introduce and familiarize our members and potential new members with our terms. With this in mind, I don't feel moving the Glossary and leaving the Resources without one is a good idea.

  But we can add/duplicate this in our future contributing/style guide or have a standalone section in this docs.

These all that I can think of as for now. I will add if I have more thoughts and ideas. 👍🏼

[BekahHW]

I'm all for standardizing and creating a style guide as @adiati98 suggested like the OpenSauced one.

I think it's ok to either have the glossary in both places or to link from one to the other.

Let's keep this in mind: this repo is a community resource. Our site is specific information for members of VC. So when making changes to this site, we should ask: is this something an external community builder needs to know? In how much depth do they need to know it?

For VCIO: is this something a member needs to know? In how much depth do they need to know it?

I know it can get a bit fuzzy. For example, does a member need to know how to room lead? Room leaders do. But I would say that generally, members don't need that info. Only room leaders do. So we link to it in the VCIO site.

@adiati98 i think we could probably work on this together to try to make it clearer.

[adiati98]

@BekahHW, thanks for the thoughts! Now I can see clearer which directions these all go.
I'm down for working on this together. 👍🏼

[meg-gutshall]

This issue came up again recently. After chatting with Ayu, it seems best to remove the List of Coffee Table Groups page from VC-Community-Docs and let it live only in VCIO to cut down on the manual tasks when there are changes. However, I'm still unclear as to where the Coffee Table Group guides documentation should reside, since it's VC-specific but not relevant to all members.

[BekahHW]

@meg-gutshall The names of people in the community should stay on the VC website. Let's keep try to make this repo a reference space for learning more about what we do and how we do it, not who's doing it and when. If that makes sense.

[meg-gutshall]

@meg-gutshall The names of people in the community should stay on the VC website. Let's keep try to make this repo a reference space for learning more about what we do and how we do it, not who's doing it and when. If that makes sense.

I believe so. By that logic, I will remove the list of Coffee Table Groups from this repo and maintain it solely in the vcio repo. The CTG-specific guides in this repo will remain intact. That takes care of one area where duplication was occurring as well. 👍

[meg-gutshall]

Based on the most recent feedback to my PR, I think we need to discuss this topic more.

I was asked to generalize the different Coffee Table Guides by removing names of Slack channels and other specifics. I didn't think this repo was supposed to be that generalized and, if so, I am going to push back hard against that decision. This repository began as vc-contributors and was meant to record internal processes, volunteer roles, and other administrative affairs.

It feels like it has now been changed into something different without a clear place for the original vc-contributors content to reside. This has led to duplication, confusion, and frustration every time I need to update something. If the VC-Community-Docs project is truly a resource for other communities and isn't meant to serve Virtual Coffee, we need a designated space in the website to house the vc-contributors content – something for active volunteers to reference.

[BekahHW]

@meg-gutshall maybe this better organizes up my thoughts:

Playbook → VC-Community-Docs

• General repeatable processes.
• Policies, rules of thumb, expectations.
• Maintainer/Community Leader-focused.
• Evergreen (doesn’t need constant updates when a host changes).

Static process docs that rarely change belong in GitHub.

If the audience is contributors/maintainers/community leaders: → VC-Community-Docs.

Directory → VirtualCoffee.io

• Living info about people, place, time.
• Group lists, current leaders, how to get involved.
• Member-facing.
• Needs frequent updates.

Dynamic information (changes monthly/quarterly) belongs on the main site.

If the audience is community members or prospective joiners: → virtualcoffee.io.

IMO, cross-linking is the solution. Every group entry on virtualcoffee.io should link back to the process guide.

There is another programmatic option. I think we could keep coffee-table-groups.yml in a dedicated repo and have both sites fetch the raw file at build time and display whatever is useful.

[meg-gutshall]

IMO, cross-linking is the solution. Every group entry on virtualcoffee.io should link back to the process guide.

There is another programmatic option. I think we could keep coffee-table-groups.yml in a dedicated repo and have both sites fetch the raw file at build time and display whatever is useful.

Okay. We're not doing this effectively with the Coffee Table Groups right now. We may want to investigate this other option you suggested.