docs: add mermaid diagrams redo

[CBID2]

Linked Issue

Closes #516

Description

This is a redo of pull request #520. I created Mermaid diagrams to create visual workflows of three major community processes:

• Lightning Talk Project Workflow — docs/lightning-talks/processes/project-workflow.md

• Facilitating a Challenge — docs/monthly-challenges/facilitate-a-challenge.md

• Lunch & Learn Guidelines — docs/lunch-and-learns/process-docs.md

These diagrams provide an at-a-glance overview of how each process flows, making it easier for new volunteers and contributors to understand their roles and responsibilities.

@BekahHW, I would love your feedback on this.

Methodology

Following the official Docusaurus v3 Mermaid integration guide, I
:

1. Added @docusaurus/theme-mermaid to the docusaurus.js.config file and enabled Markdown support.
2. Translated three existing textual workflows into clear, concise Mermaid diagrams.
3. Ensured consistency in visual style and logical flow across all diagrams.
4. Tested each Markdown file to confirm correct rendering in local preview.

These changes improve readability, onboarding efficiency, and process transparency by combining structured documentation with visual context.

Code of Conduct

By submitting this pull request, you agree to follow our Code of Conduct

[netlify]

❌ Deploy Preview for vc-community-docs failed. Why did it fail? →

Name	Link
🔨 Latest commit	cc66323
🔍 Latest deploy log	https://app.netlify.com/projects/vc-community-docs/deploys/68eabb4303cfd900085238af

[netlify]

✅ Deploy Preview for vc-community-docs ready!

Name	Link
🔨 Latest commit	f0e66f6
🔍 Latest deploy log	https://app.netlify.com/projects/vc-community-docs/deploys/69057a0296cc550008469921
😎 Deploy Preview	https://deploy-preview-521--vc-community-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[BekahHW]

@CBID2 I like the direction this is heading! It looks like the only file update with the diagram is the Lunch and Learns. You might need to commit and push the latest changes.

To make it easier to read and remove a lot of the white space, can we update the Mermaid diagram to use a two-column horizontal flow with subgraphs?

This version groups related steps into logical sections (Planning, CFP, Prep, Event, Post-Event) and displays them left to right rather than top to bottom. It makes the diagram more compact and scannable.

Here’s an example of the structure to follow:

flowchart LR
  %% Planning
  subgraph A[🛠 Planning]
    A1[📢 Call for Team] --> A2[👥 Onboard Team]
    A2 --> A3[📝 Assign Coordinators]
  end

  %% CFP
  subgraph B[📬 CFP]
    B1[📣 CFP Opens] --> B2[🧾 Collect Proposals]
    B2 --> B3[👩‍💻 Grouping]
  end

  %% Speaker Prep
  subgraph C[🧭 Prep]
    C1[🗂 Organize Talks] --> C2[✅ Checklists]
    C2 --> C3[📸 Speaker Info]
    C3 --> C4[📁 Shared Folder]
  end

  %% Event
  subgraph D[🎤 Event]
    D1[🧾 Final Prep] --> D2[📨 Directions]
    D2 --> D3[🧑‍🏫 Talks]
  end

  %% Post
  subgraph E[🎥 Post-Event]
    E1[☁️ Upload to YouTube]
  end

  %% Flow
  A3 --> B1
  B3 --> C1
  C4 --> D1
  D3 --> E1

Also, when I'm looking at the L&L file, the text is getting cut off:

I'm on chrome. Not sure which browser you're using, but that's something to investigate.

[CBID2]

@CBID2 I like the direction this is heading! It looks like the only file update with the diagram is the Lunch and Learns. You might need to commit and push the latest changes.

To make it easier to read and remove a lot of the white space, can we update the Mermaid diagram to use a two-column horizontal flow with subgraphs?

This version groups related steps into logical sections (Planning, CFP, Prep, Event, Post-Event) and displays them left to right rather than top to bottom. It makes the diagram more compact and scannable.

Here’s an example of the structure to follow:

flowchart LR
  %% Planning
  subgraph A[🛠 Planning]
    A1[📢 Call for Team] --> A2[👥 Onboard Team]
    A2 --> A3[📝 Assign Coordinators]
  end

  %% CFP
  subgraph B[📬 CFP]
    B1[📣 CFP Opens] --> B2[🧾 Collect Proposals]
    B2 --> B3[👩‍💻 Grouping]
  end

  %% Speaker Prep
  subgraph C[🧭 Prep]
    C1[🗂 Organize Talks] --> C2[✅ Checklists]
    C2 --> C3[📸 Speaker Info]
    C3 --> C4[📁 Shared Folder]
  end

  %% Event
  subgraph D[🎤 Event]
    D1[🧾 Final Prep] --> D2[📨 Directions]
    D2 --> D3[🧑‍🏫 Talks]
  end

  %% Post
  subgraph E[🎥 Post-Event]
    E1[☁️ Upload to YouTube]
  end

  %% Flow
  A3 --> B1
  B3 --> C1
  C4 --> D1
  D3 --> E1

Also, when I'm looking at the L&L file, the text is getting cut off:

I'm on chrome. Not sure which browser you're using, but that's something to investigate.

Hi @BekahHW! I made the changes you requested. The only issue I have now is how to make the merimad diagrams bigger so users don't have to use the Zoom in feature on the browser. Can you help with that?

[BekahHW]

@CBID2 can you tell me what you've tried or link to the resources you looked up so far?

[CBID2]

@CBID2 can you tell me what you've tried or link to the resources you looked up so far?

Hi @BekahHW! :) I made the diagrams bigger

[CBID2]

Hey @adiati98! Can you review this? 😁

[adiati98]

Hey @CBID2 ,

I'm currently on vacation, so I can't take a look at this closer.

But I've seen some diagrams on my phone:

1. Some arrow parts are behind the box as screenshot below:

   

2. Some boxes in a diagram are way too big, while in the following diagram, the boxes are small. Probably make them a bit proporsional? On the phone, it looks like some diagrams are on the left side and not centered.

   

3. We never do automation for monthly challenges. Where did you read this on the docs?

   

Can you please read and confirm with the docs when creating the diagram? If you need help, let us know. 🙂

---

@BekahHW, can you take a closer look at this? TIA! ✨️

[BekahHW]

These are looking really good! A couple of concerns:

• Because they're vertical, they take up a lot of space and so the users might miss the actual documentation. It's worth exploring a horizontal path.
• I'm a bit worried that the diagrams aren't clear and also want to make sure they do align with the processes documented. The key here is that it should make it easier for the user to grok the process. If they look at the diagrams and can't really understand what to expect, then we've missed the mark. Ask yourself if you could generally coordinate the events based on the diagrams you've created.

[CBID2]

These are looking really good! A couple of concerns:

• Because they're vertical, they take up a lot of space and so the users might miss the actual documentation. It's worth exploring a horizontal path.
• I'm a bit worried that the diagrams aren't clear and also want to make sure they do align with the processes documented. The key here is that it should make it easier for the user to grok the process. If they look at the diagrams and can't really understand what to expect, then we've missed the mark. Ask yourself if you could generally coordinate the events based on the diagrams you've created.

Hey @BekahHW. I think I got this time

[adiati98]

I feel like it'd be more useful if the diagram is inside its section than standalone at the beginning of the page. It can be before the written docs or after for a better visual. The reason is that it'll be easier for folks to see and read both the docs and diagram in the same place rather than to scroll back and forth between the diagram and written docs.

@BekahHW any thoughts on this?

[dominicduffin1]

@CBID2 I have some comments on the Monthly Challenge docs. I realize existing documentation is not fully representative of what we are doing but since we are making updates I'd like to ensure we are reflecting current processes.

---

I'm generally concerned that the diagrams suggest a level of process organization that we are not really doing right now. In an ideal world we would be doing it or something equivalent but with limited bandwidth on the team we often fall back on simpler processes.

---

Announcements

I have a template I use for the Slack announcement instead of going through a draft -> feedback -> approval process every month.

I'm not aware of any social media posts announcing monthly challenges.

I'd like to get input from the @Virtual-Coffee/maintainers on the "Send to Email List" step as I don't have visibility into this but I'm not sure it is correct to imply a direct link between the Announcement tasks and the email list as I don't do anything in this regard as part of my work on the announcement.

Post challenge

The diagram makes a specific link between "Community Engagement" and "Gather Feedback" but we don't currently have any process to gather feedback from the community. I'd like to have such a process but we don't have the bandwidth to do this effectively at present and I'd prefer the docs to represent reality rather than aspiration.

We do update documentation to reflect what we did during the challenge where new elements were introduced that year. I think the "Update Documentation" should be directly linked from the "During Challenge" section as this is not something that occurs as a result of community engagement or feedback.

We do from time-to-time gather feedback from within the team post-challenge. This feeds into planning of future challenges. Ideally the diagrammatic structure would reflect that flow between team feedback and planning in a circular flow leading back to the earlier stages.

Team Cooridnation

I'm concerned that this workflow is stating the obvious without really giving any information about what we actually do. Having said that, since how we do this isn't really documented, this is not your fault. We can probably revisit this section in future.

---

We also update the #monthly-challenge Slack channel topic and description each month. This step is missing from the diagrams. Maybe we could have a "Day 1" diagram that includes posting the announcement and updating the Slack channel as I usually do these two tasks at the same time.

I'd also like to see a link between the website updates and the announcement as I lift one or two sentences from the website to fill into my announcement template and add to the channel description.

---

Let us know your availability for the challenge in the reminder thread that drops every mid-month in the #vc-monthly-challenge-team channel in Slack.

We don't use this reminder thread any more, although it is still posted by Slackbot each month. Ideally, since we are making updates I'd like to remove references to this, although it can be done separately.

---

@adiati98 @BekahHW Please feel free to chime in if you disagree with anything I've said or feel it doesn't accurately reflect your roles in our processes.

[adiati98]

@dominicduffin1, I think as long as the diagram based on the workflow that are stated in the docs, that should be fine for now. That means, we need to update our docs to follow the current workflow in another issue.

But I do agree with you for some flows that aren't based on the docs here:

1. Announcements:

   • We don't announce monthly challenges on social media.
   • We never do e-mail list to send out monthly challenges in any form. --> @Virtual-Coffee/maintainers can you please confirm?
   • We don't need get feedback & revise, also final approval.

2. Post Challenge:

   • As stated in the docs: Provide feedback in the #vc-monthly-challenge-team channel. --> This channel is our team's private channel. That said, we gather feedback from our team members, and not the community members.

3. Team Coordination:

   It seems like it's meant for the flow of Coordinating with the Coffee Table Groups. However, the diagrams don't capture the flow as per docs.

---

@BekahHW can you also please check the diagrams for L&L and Lightning Talk?

---

@CBID2 I'd like to know how did you come up with the workflow? Same as Bekah, my concern is the diagrams are not clear and not align with the workflows documented here. Please let us know if you have any questions.

[dominicduffin1]

@adiati98 @CBID2 Agreed that we can focus on representing the docs as currently written for this issue.

A couple more points i still think should be addressed:

1. I don't think there should be a link between feedback and documentation in the post challenge flow. Our current docs correctly don't imply this link.
2. We should include updating the challenge channel along with announcements as this is included in the written docs

[CBID2]

Hey @adiati98 and @dominicduffin1, I took your advice and revised my diagram for the Facilitating a Challenge docs here: https://mermaidviewer.com/share/rK_eOP-lHtMT0ib8YZzog
What do you think?

[dominicduffin1]

@CBID2 I think this is getting closer. Overall, I think this version of the flow represents things fairly accurately.

I still have some feedback:

1. A minor one about word choice: We refer to those who lead teams as "Lead" not "Leader". There was a wider conversation about this a while back but I believe we concluded in favor of that. Otherwise, I think the planning flow is fine.
2. We need to put back the step of updating the website in the promotion flow. Also, I think we should say that the challenge is announced in #announcements and have a separate step for updating the #monthly-challenge channel.
3. Another minor one in the check-ins section: Mondays at 10am is goal setting not progress updates.

@adiati98 @BekahHW Do you have any other thoughts?

[BekahHW]

I added the hacktoberfest-accepted label to make sure you get credit for this, @CBID2. I'm thinking that we might want to put the diagrams in a details section, so people can opt into looking at it. I think this makes sense, especially if someone is on a mobile device. These get a bit lengthy.