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