community resources & accessible open-source

[chazkiker2]

Resources for an Accessible/Productive Open-Source Community

(First, a brief introduction) — Hello to all of the Fractal Protocol team members, even those I haven't met yet! My name is Chaz; I've been interviewing with @shelbyd for the past month or so. I may be joining y'all shortly! Nice to meet you all! 👋

Motivation

Since Fractal is an open-source protocol, its community will likely want to contribute & get involved with our codebase. As the community grows, so too will the need/desire for welcoming documentation, guidelines, and accessible learning.

Though this isn't the highest priority for Fractal at the specific moment, I personally think it's one worth talking about early and often. And, usually, getting open-source resources started is a fairly simple thing since (1.) documents don't need to be in perfect shape, and (2.) choosing tools, processes, etc., is not in any way a permanent decision!

I skimmed through the codebase here the past few days and thought it could be more approachable to outsiders.

@shelbyd, I'm sure you have ideas and opinions for how you'd like this to carry on. My only intent with opening this discussion is to kick off the conversation. All the ideas here are in no way set in stone. Just tossing them out there in case they're useful—I'd be happy to hear any opinions y'all have on any of the following points!

Background: Big Picture

Each open-source community that I've worked with has varied immensely in (1.) the type of project they were developing, (2.) the tools and processes they use to build. However, at a higher-level scope, they all set out to achieve similar goals regarding their open-source:

• document their actual code (for the end-user or APIs or whatever)
• documentation beyond the code
  • progressively document and iterate on the project vision
  • share status of the project (triage, Trello board, etc.)
  • "learn out loud" (or "grow out loud" as the case may be). For example: making notes of developer experiences working with X.
  • openly share resources, tutorials, examples
• communicate & connect with their community; provide a space where members may:
  • ask for help on a specific problem
  • ask for guidance on a general problem
  • seek mentorship in how to contribute
  • Share an idea or request a new feature
  • point out a bug/issue
  • chat, converse, or make new connections with other members
• allow their community members to help in deciding upon the tools and processes to use!

Prompt

I would love to hear anyone's thoughts on:

• what are your personal hopes/ideas/preferences for open-source processes?
• how do you think Fractal Protocol should pursue any of these fronts?
• what are the specific values of open-source communities that you especially prioritize?
• examples of other communities that do X well
• any tools/apps/mindsets that they personally enjoy for open-source collaboration?

[chazkiker2]

example of an amazing open-source community: rust-lang

Of all the open-source communities I've interacted with, rust-lang is an especially fantastic one.

• Things that are great about rust-lang's open-source practices:
  • heavy use of Zulip as an asynchronous communication channel SPECIFICALLY for development or project-related discussion.
    • This is not considered the place for random questions, end user questions, or conversational threads; but it is a very accessible place to converse project-related matters. It's fantastic for contributors.
    • @shelbyd, I think you'd especially like Zulip as a communications platform if you like Pivotal Tracker as a tracking platform.
  • Truly unprecedented documentation, guides, and learning resources across the board. The prolific use of mdBook adds a notable layer of higher-level documentation (the "documentation beyond the code") that doesn't exist to the same extent in other ecosystems.
    See wg-async-foundations as a REALLY great example of organizing information for an in-progress project! I think this sort of thing would be super valuable for Fractal Protocol. (See [PROPOSAL] docs: add initial md-book  #23 for what this could look like.)
  • a heavy emphasis on maintaining a welcoming community — people are friendly, insightful, inclusive, and willing to help.
  • opportunities for mentored contributions
  • emphasis on GitHub Issues as the driving force of development (almost all PRs in rust-lang/rust fix an issue)
    • Issues are well categorized and labeled.
    • Communication over Issues & PR is plentiful.
    • Leads to some really focused PRs and some useful metrics for tracking project health
    • use GitHub Projects as a project Tracker, which integrates nicely with GH Issues, naturally.
    • this makes contributing SUPER easy. toss a [mentored] or [good first issue] tag on an issue to toss an easy one to a newcomer.
• Things that I don't love as much:
  • since Rust's Zulip channel puts such an emphasis on project-related focus, more conversational interactions happen in Discord.
    • adds yet another app to the mix
    • people with an immense preference for Zulip may not participate as much in the Discord as a side effect (and vice versa)
    • potentially isolates casual end-users from active rust-lang contributors — debatable whether this is (1.) relevant or (2.) a pro or a con... I think this point matters less if documentation and community is solid elsewhere

Personal Preferences

• I'm a huge fan of the "learning out loud" side of things. I think it's immensely useful when a project open-sources everything that is safe to open-source. Once again, rust-lang is a primetime example.
• huge fan of Zulip as a primary platform for async communications between developers/contributors specifically. I like Slack for this, too, but I still prefer Zulip.
• huge fan of Discord as a more general platform for community interactions (especially the more conversational ones)
• mdBook is an amazing tool for higher-level documentation (beyond the code). I definitely think Fractal Protocol should have a mdBook (See [PROPOSAL] docs: add initial md-book  #23 for what this could look like.)
• really big fan of using HackMD for certain documents (like RFC drafts)

[shelbyd]

Thanks a ton for taking the initiative to contribute (especially before possibly joining). There are a lot of ideas here and many different things we can take on. What would you put as the highest priority items? Alternatively, what are the biggest problems you see us facing (even if you don't have solutions)?

I would think our top priority things (in terms of impact per unit effort) are:

1. A markdown file of good existing resources. Basically a "start here" page.
2. A "Processes" page that describes how we approach development, so if someone wants to contribute they can start there. That would include links to our Pivotal Tracker project, GitHub discussions, CircleCI builds (maybe?), and anything else that only contributors would really care to see.

Not sure what else has a really high ROI right now. We do need to balance education and community development with "getting shit done". ATM, I'm more on the GSD side of things, and we can work on the community once more people are interested in the shit we've already gotten done.

[chazkiker2]

Agreed that the "end version" of the resources & community stuff is not the primary concern right now.

And I agree completely with the two top priorities that you listed. Though I'd maybe change "Processes" to CONTRIBUTING.md for the sake of findability. And maybe also including a formal contributing process and an easy list of "Priority Tasks" that they could look through in case they were motivated by a specific feature/issue or whatever.

Once those are in, it'll at least be enough for anyone who stumbles across this codebase and wants to explore a little bit.

Thoughts?