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#Practice_radical_transparency_from_day_zero

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