I had a discussion this weekend with Amber Graner, and was struck by her
recollection of the short, meaningful phrases that are hallmark of the
1.0 release. This is not the first time I've heard that from folks--the
original focus on PIE (principle, implementation, example) for
what/how/why had the effect that we kept the 'what' to a very short,
focused sentence or two.
In this new version we want more of a narrative flow, and I also think
we don't want to lose the summary-short statements that get to the heart
of the matter.
Here is what I've been thinking for the format of each chapter, which is
informed by all the recent discussions:
2. Summary aka tl;dr -- summary of salient points from the chapter,
offering a chance to give the main points in short, memorable phrases.
3. Main content -- bulk of writing goes here
4. Stories of why -- the chapter author brings some of these stories,
but they can be swapped out with other stories from the
5. Lexicon -- capture of various special terms in the chapter so there
is one place explaining the terms.
It's the summary/tl;dr that acts most like the 1.0 chaplets, for example:
So the memorable phrase in that example is from Karl Fogel, "Making
important decisions in private is like spraying contributor repellent on
Writers main concerns would be around 3. the main content, from which
the tl;dr and initial stories-of-why arise.
How does that sound to you?
Karsten Wade [he/him/his]| Senior Community Architect | @quaid
Red Hat Open Source Program Office (OSPO) : @redhatopen
https://community.redhat.com | https://next.redhat.com | https://osci.iohttps://theopensourceway.org | https://github.com/theopensourceway/guide
We ran a BoF discussion at FOSDEM around our efforts to revamp TOSW. I
took some notes, and Erin McKean was kind enough to send me her notes.
I've compiled some notes below from mine and Erin's.
There was some discussion around what kinds of contributions (and what
kinds of contributors) you want to encourage, and on the flip side,
what kinds you do not want to encourage. For example, how do you handle
well-meaning attempts to clean up the code base that break API?
There's interest in advice on running events. Running a major
conference is probably out of scope, but there are lots of tips for
running smaller events and hackfests.
Is it possible to scale down the guide for smaller projects? Some
projects don't need all the information. Can we have a journey thru the
guide that's relevant to newer or smaller projects?
How do you deal with toxic contributors? And how do you deal with the
mental health of moderators and community leaders when they have to
deal with toxicity?
Is it impersonal to just put this all in a written guide? Part of the
motivation for writing the guide is to have something to reference when
people ask about open source, but is telling them to "RTFM" really the
There was some discussion on whether to talk about projects,
initiatives, or some other term. We seem to be preferring project, but
that is very software-centric.
For profit-generating projects, how to you reward contributors when
there's money flowing, especially outside employment? Does paying
contributors disincentivize people from contributing without pay?
How do you get funding and resources? Corporate sponsors are a source,
as well as programs like Summer of Code and Outreachy. There are
services with free tiers for open source projects. It was pointed out
that these services change frequently, so the content might not be as
evergreen. Job for an evolving wiki?
There was considerable discussion about generalizing the guide to non-
software projects. A lot of the planned material is relevant to all
sorts of communities. There's definitely interest in including examples
from other free culture movements (music was brought up as an example),
but we don't want to stray too far.
There was further discussion about writing in a modular fashion, which
could allow topics to be reused with different examples. Modular
writing is good, but can create a barrier to entry if done too much.
How do you resolve conflicts between stakeholders? Aside from personal
conflicts, there can be legitimate differences in technical direction
that can affect how your project progresses.
A lot of what we discussed was about running distributed communities
across the globe. How do these concepts translate to situations where
you're meeting people in-person?
There was general discussion about metrics, but one concrete question
was how do you decide when you need more community leaders?
How do you define a vision, roadmap, and project goals? How do you
prioritize these goals and get community feedback when prioritizing?
How do you handle loss of contributors, offboarding, and succession?
Relatedly, how do you decide when to end a project, and are there
processes for ending gracefully?
Some discussion on forking or taking over projects, and in particular
how legal stuff like trademarks comes into play.