11:53 a.m.
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:
1. Title
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
interview/story pool
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:
http://www.theopensourceway.org/wiki/How_to_loosely_organize_a_community#...
So the memorable phrase in that example is from Karl Fogel, "Making
important decisions in private is like spraying contributor repellent on
your project.
<http://producingoss.com/en/setting-tone.html#avoid-private-discussions>...
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
--
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.io
https://theopensourceway.org | https://github.com/theopensourceway/guide
12:38 a.m.
This got stuck in the moderator queue by accident, I'm bumping it here to make it
visible for discussion.c
8:04 a.m.
Thanks Karsten that structure looks fairly straight forward.
Can I ask for some clarification on the context of “Stories of Why” sections and what
content would that contain. My interpretation was that these stories of why would be
examples and experiences from either the author or interviewees that help emphasis the
points described in the main content. However, is this section required to be segmented
separately from the main content or can “Stories of Why” be references slotted within
context of the closely related sub-chapters of the main content if appropriate?
Tried to lay out a structure for chapters that contain sub-chapters to help propose the
idea
(https://github.com/theopensourceway/guidebook/blob/master/developing_a_me...)
e.g.
Developing a Metrics Plan/Community Metrics (Chapter Title)
> (Chapter Summary)
> (Main Content)
>> Why metrics are important in Open Source communities (Sub Chapter Title)
>>> (Summary) *This required?
>>> (Sub Chapter Main Content)
>>> Provide objective measures
>>> Transparency: Know who is contributing and where contributions are happening
(especially as project/community grows)
>>> Encourage community participation: Are new contributors joining the
community? Who are some of the regular contributors in the community?
>>> Identify potential bottlenecks in the community: Are bugs/issues being close
in a reasonable timeframe? Are reviews happening in timely manner?
>>> (Stories of Why relating to Why metrics are important in Open Source
communities )
>> Developing metrics for your community (Sub Chapter Title)
>>> (Summary) *This required?
>>> (Sub Chapter Main Content)
>>>Take advantage of APIs, dashboards, plug-ins, etc. that are available in your
software tools (e.g. forums, code repositories, issue trackers, wiki’s, etc.)
>>> Resources/examples from other communities: Lot of communities have good
documentation/code for their dashboards (e.g. CNCF, Ruby, etc.)
>>> The CHAOSS project (https://chaoss.community) develops metrics definition and
sample implementation for open source communities.
>>> (Stories of Why relating to Developing metrics for your community)
Understandably not all sub-chapters may have enough content for a Stories of Why section
within but felt that it would still be logical to provide these stories as relevant
‘evidence’ to support the points made in the sub-chapter for immediate consumption rather
than at the end of the full chapter.
Of course this is the assumption that we will have a selection of choice per chapter or
even sub chapter and that they're not all so similar or described at such a high level
that it would be best to combine in a single section. :)
Love to hear any thoughts or perhaps worry about it when we get to the Stories of Why. +1
12:27 p.m.
On 4/16/20 6:04 AM, Ashley Nicolson wrote:
Can I ask for some clarification on the context of “Stories of Why”
sections and what content would that contain. My interpretation was that these stories of
why would be examples and experiences from either the author or interviewees that help
emphasis the points described in the main content. However, is this section required to be
segmented separately from the main content or can “Stories of Why” be references slotted
within context of the closely related sub-chapters of the main content if appropriate?
That is a good clarification. I agree that we will want and end up with
why-content embedded in the in the main content, as part of the
narrative flow.
Would it make sense to define the "Stories of Why" as supplemental
stories that re-emphasize points made in the chapter?
So there isn't a forced segmentation as much as a way to include
meaningful stories as needed.
- Karsten
--
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.io
https://theopensourceway.org | https://github.com/theopensourceway/guide
9:53 a.m.
I think starting with a tl;dr is a good idea, acknowledging that people
don't always read long-form text. We could also use pull quotes for
some salient points, but that does mean the writers have to write
things that are pull-quotable.
//Shaun
On Mon, 2020-03-30 at 09:33 -0700, Karsten Wade wrote:
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:
Title
Summary aka tl;dr -- summary of salient points from the
chapter, offering a chance to give the main points in short,
memorable phrases.
Main content -- bulk of writing goes here
Stories of why -- the chapter author brings some of these
stories, but they can be swapped out with other stories from
the
interview/story pool
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:
http://www.theopensourceway.org/wiki/How_to_loosely_organize_a_community#...
So the memorable phrase in that example is from Karl Fogel,
"Making important decisions
in private is like spraying contributor repellent on your
project."
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
--
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.io
https://theopensourceway.org |
https://github.com/theopensourceway/guide
_______________________________________________Contrib mailing list
-- contrib(a)theopensourceway.org
To unsubscribe send an email to contrib-leave(a)theopensourceway.org
1725
days inactive
1742
days old
4 comments
4 participants
participants (4)
-
Ashley Nicolson -
Karsten Wade -
Karsten Wade -
Shaun McCance