Augment and standardize references

[semioticrobotic]

Guidebook should feature a list of in-text references and suggested additional readings.

[kayleachampion]

Hi, I'd like to help with this issue! In particular, I am eager to walk through the book and add connections to research/evidence drawn from social computing scholarship (I had a chance to speak briefly with @quaid about this at CHAOSSCon). I have two questions -- one scope-oriented and one pragmatic.

Scope:

Can you say a bit more about what kinds of references and/or what approach to those references you think readers would find most helpful? I've thought of five ways that research/references might be useful in this guide -- which of these (or perhaps none?) do you think would best serve the book, and if more than one, what priority order?

1. A "Read More" section at the end of chapters; this could be done as a more raw (but shorter) bibliography design, or in an 'annotated bibliography' style where some text (ranging from a phrase to perhaps 3 sentences) describes what you'd get if you read reference X. This could probably be done relatively quickly.
2. Footnotes that directly reinforce what's already said and could be presented "naked" without editing the text that precedes them, i.e. I'd be adding a "[1]" or "(Author & Author 2017)". These might be a bit rare.
3. Sentences or paragraphs that augment what is already present using references to research, e.g. something in the contribution motivation section might go like this:
   These differences in motivations also shift how different kinds of contributors respond to different contribution barriers. If your project needs a particular kind of new contributor, focusing your effort on reducing barriers specific to that kind of contribution can help (Hannebauer and Gruhn, 2017). For example, new contributors who are eager to add specific new features are more likely to be discouraged if they can't find where in the code they should make their changes. Contributors who are motivated by a hope for social connection are more likely to become discouraged if they find it difficult to make direct contact with other participants.
4. Sentences or paragraphs that reference some amount of uncertainty, scholarly debate, active research, etc.
   "Early research into open source often described projects as having an "onion" structure. The onion structure divides contributors into layers: highly active 'core' participants who make major decisions and write most of the code, 'peripheral' participants who fix bugs, 'users', who make bug reports and feature requests, and so on. In this model, participants move through phases, from user to core participant. However, recent research has cast some doubt on this model, at least over the long term and with larger projects. A 2021 study from Christian and Vu looked at 15 years of contributions to the LLVM compiler infrastructure. They found that bug fixing was a community-wide activity, not a function of where individuals fell in a 'core-periphery' structure. Christian and Vu also observed that the relative role of bug fixing in the community tends to shift over the lifecycle of a project. In addition, as Jergensen, Sarma and Wagstrom observed in their 2011 study of the GNOME project, many open source projects are part of an overall ecosystem with similar norms and technologies in use: newcomers may not be all that "new" and able to skip layers in the onion. Some lessons that community leaders can learn from this line of research are: avoid assumptions about the kinds of work that different participants can or will contribute, examine and re-examine onboarding materials and processes to see if they match the project's current needs, and think about the role of the project's ecosystem and where the project might be in its lifecycle."
5. Research Spotlights or Case Studies. These would be standalone little sections -- in a typeset book, the kind of thing that might appear as a side bar, in a box, etc. In 2-3 paragraphs, maybe with a picture or graph or two (reprinted with permission), a research spotlight or case study would give the who-what-when-where-how-who cares of a published study. One good example of this might be drawn from a study that Klug, Bogart, and Herbsleb did on the Rust community -- talking about how Rust develops its roadmap by first synthesizing across 100+ blog posts from high-volume contributors detailing their plans, then ordering the work into phases, and then using it to guide work -- the researchers analyzed just how much the roadmap was followed (answer: reasonably well) and whether it seemed to turn into an onerous restriction (answer: not really). For this I'd probably want to contact the authors as well as Rust folks; I assume they'd be thrilled to have their study and process show up in a book, but it seems like an opportunity to partner rather than 'surprise' someone :). This is probably the most involved of the five ideas I am describing.

Pragmatic

I see a few in-text citations done in a typical style (Author, year), but I'm mindful of the fact that too many citations can bog down reading for folks that aren't accustomed to reading research papers non-stop. As an alternative, the Association of Computing Machinery (professional society for tech scholars) uses a footnote style of bracketed numbers [1]; or there's always superscripted numbers. I'm happy to follow what's already present, but wanted to ask before I went too far down this road.

About me:
I'm a PhD candidate in the Department of Communication at University of Washington, and I study how people collaborate to build groovy information public goods like Linux and Wikipedia. This quarter I am the teaching assistant for the Online Communities class being taught by Benjamin Mako Hill, so I'll be knee deep teaching undergrads a lot of the same concepts that The Open Source Way discusses. Before graduate school I was a sysadmin and worked tech support; I've been using Linux since 1994.

[quaid]

Hiya @kayleachampion great to see you again! I'm starting with a resounding "YES MORE PLEASE", but let me step through this including the administrivia up front. Also, some serendipity is that Mako was directly and strongly influential on me and the ethos of the 1.0 version of the Open Source Way, possibly also some attributable content in there somewhere, perhaps in an archived Subversion repository. :)

Administrivia

• I sent you an invite to this GitHub org. We've been using some of the organizational features around Issues, such as the project boards—if you haven't seen the board this Issue theopensourceway/guidebook#36 is tracked on it's worth a look—and you need to be a member to be assigned to an Issue. (Specific thoughts on that below.)
• Tagging in my close comrade and colleague @semioticrobotic, because this is an area of interest and study for him AIUI, and I think the three of us can make some reasonable decisions and/or recognize we need more people involved.
• For the meta-discussions across the community, please join

Wow

These are great ideas, I pretty much understand what you mean and can fully envision the value, look and feel on the page, risk and reward of Too Much Information, and so on.

We absolutely have been talking about a print-ready version of the guidebook (and available as print-on-demand) as a feature of the 2.1 release. The 2.1 release is currently an idea that needs some discussion on the mailing list, so there is time to look into designing it around spotlight boxes and so forth.

On the other side of this from the research/academic expertise, we have contributors and friends-of-the-project with solid publishing and design/layout experience. It seems reasonable to me we can find a happy balance of whitespace, layout, and useful and accessible references.

Pragmatically, my first thought was to see your five ideas done in phases, with a few ideas or even caveats around that.

Whatever priority order we pick, we want to think of it in classic journalistic reverse-pyramid in case we don't get all the steps done in time for 2.1 to go to print. (We can also update a print-on-demand source, I reckon, if needed.)

That suggests we open an Issue for each of the numbered items (or whatever set we settle on), which can then be assigned and worked on by you. The Issue can then be tied to one or more Pull Requests (PRs), when you are working on and/or specifically contributing content into the repo.

(Note these processes that rely upon GitHub are being used for convenience, as the primary purpose of being on GitHub is the social contributing factor; it's always been on the not-yet-written-down roadmap to regularly reconsider leaving for a FLOSS platform, which is one of the reasons I have my eye on IEEE SA OPEN's assurance of using GitLab CE so as to build an all-open source git forge.)

Finally, my thought on the Too Much Information question is to resolve it with design. Make it findable and available, but not overwhelming and crowding. 😁

Thanks again for your interest and enthusiasm, I'm super excited about this work and would love to help find the path to a swift and useful step one.

[kayleachampion]

Great! Thanks for the invites and warm welcome. Looking forward to plotting a solid course toward the first PR :).

[semioticrobotic]

This is so great! Thanks, @kayleachampion, for jumping in here and sharing such awesome ideas.

As for the Five Options Discussion, I'll simply state my preference, which at the moment is something like: standardize on footnotes as the mechanism for in-text citation (2) and revisit previous writing to add additional research, context, and detail in places that could use it (3).

I think end-of-chapter "Additional Resources" sections (1) are nice to have but more likely a stretch goal at this point. And I think the sidebars with case studies (5) are really nice to have, but even an even further stretch at this point in time.

Regardless of what we decide, @kayleachampion I would gladly volunteer to assist you with this work (as @quaid is correct that it's something in which I'm invested). When we determine the scope of our initial foray into the work, we can rename this issue to clarify it (since "Compile References," while a succinct and hastily recorded thought, isn't perhaps the most specific description of what we're trying to accomplish here. 😄)

[kayleachampion]

Thanks for the scoping feedback @semioticrobotic :) -- seems like we are converging on a plan. One more option occurred to me: maybe an item (6) as an alternative to (1) would be an end-of-book section called "Further Reading" or similar. I have several in mind -- Benkler's Wealth of Networks, Kraut & Resnick's Building Successful Online Communities, Eghbal's Working In Public, etc. A separate section would keep this task out of the critical path for v2.1 also, since it's modular -- if it doesn't land, it can await the next release without looking awkward.

For what it's worth, the online communities class I'm TA'ing is starting up next week -- we start with motivation and commitment, then talk about norms and governance, then newcomers, then topics specific to creating new communities. Roughly following this order would be particularly efficient for me.

How shall we work together? I'm comfortable throwing things out there and refining it through exchange, but could also do more synchronous/pre-planned consensus style approaches as well.

In case folks are curious, the syllabus is here: https://wiki.communitydata.science/Online_Communities_(UW_COM481_Winter_2022)

[kayleachampion]

Also -- looks like I don't have rename powers for issues. Whatever works for you is ok by me :).

[semioticrobotic]

Awesome! Thanks, @kayleachampion, for your patience as I made my way back to the computer from holiday hiatus.

First, let me say I really like your idea (6) for an "Additional Resources" section of the guidebook. This could be something like an annotated bibliography of relevant materials—might even be an assignment your students could consider tackling, if they want or need experience contributing to a beginner-friendly community project and are already doing the reading. I agree that this shouldn't be on the roadmap for 2.1, and that actually puts less pressure on us to prioritize it. I will open a separate issue for that work and reference this.

Next, then, on collaboration moving forward: I'm more than happy to following the trajectory your course is taking if that's what you're already doing (makes most sense to me). Looking at your proposal, I see the following loose order:

1. motivation and commitment
2. norms and governance
3. newcomers
4. creating new communities

So I would perhaps suggest we focus work on the following chapters to get us started:

• Why Do People Participate in Open Source Communities?
• Incentivizing and Rewarding Participants
• Project and Community Governance
• Essentials of Building a Community
• Onboarding

I see lots of opportunities for addition, refinement, and standardization here; these chapters all tend to treat references a bit differently, some include their own "read more" sections (which we can amalgamate into idea 6 above), etc.

What do you think?

If it's easy to discuss any of those synchronously, I'm more than happy to do that in a way that works for you. Just say the word.

P.S.: Thanks so much for sharing your syllabus. I enjoyed reading it. Incidentally, since Wikipedia seems to serve as a primary case study for your students, I'd also suggest Nathaniel Tkacz's excellent Wikipedia and the Politics of Openness for those interested. Do let me know how your experience with a flipped class goes. I once TA'ed a flipped course and both the instructor and I found that the method didn't really produce the results we thought it would.

[semioticrobotic]

(Noting a link to theopensourceway/the-project#85 for future reference. No pun intended.)

[kayleachampion]

Great! Would it make more sense for me to work in a fork and PR when I have something for you to look at? Branch or main?

FWIW this class has been taught quite a few times as 'flipped' and it seems to work -- but maybe a key component of that it's coupled with a 'cold call' model. Students come to class prepared because we will be calling on them and assessing their responses, and nobody wants to look bad :)

[semioticrobotic]

Great! Would it make more sense for me to work in a fork and PR when I have something for you to look at? Branch or main?

Are you able to simply create a new branch in this repository from which to work? I'll confess I'm always a bit confounded by GitHub team permissions but can look into getting you what you need to work this way.

Thanks for the feedback on your course!