An alternative Table of Contents

In light of the 1956 research paper of George A. Miller of Harvard
University, "The Magical Number Seven, Plus or Minus Two: Some Limits
on our Capacity for Processing Information"
<http://psychclassics.yorku.ca/Miller/>;, I would like to suggest a
different organization of the Tale of Contents of "The Open Source
Way":
1. The Open Source Way: Creating and nurturing communities of
contributors -- Main wiki page
2. Introduction -- What this book is, what it is not, essential
terminology (definitions and pointers)
3. Communities of practice -- The science behind the open source way
    3.1 What is a Community of Practice?
    3.2 Elements of the Community of Practice
    3.3 Principles for Cultivating Communities of Practice
    3.4 How to loosely organize a community -- Structure of a
sustainable community
    3.5 What your organization does:
          3.5.1 Right when practicing the open source way -- Distilled
"Right Way"
          3.5.2 Wrong when practicing the open source way -- Distilled
"Wrong Way"
    3.6 Business the open source way -- Applying the open source way to business
    3.7 Who else to watch -- People in the wider world who write,
talk, and lead community-oriented discussions and actions
4. Data and references -- Data and references that support the book
    4.1 Books you should read -- Online and offline resources
    4.2 Stuff everyone knows and forgets anyway -- Common knowledge,
common mistakes, common recoveries
    4.3 Great stories to tell -- Stories that illustrate the open source way
    4.4 How to tell if a FLOSS project is doomed to FAIL - A system
for evaluating the potential of an open source project
5. Appendix -- What fits not elsewhere but only here
6. Community Architecture dashboard -- Overview of this effort with pointers

And, perhaps the chapter titles could be more succinct:
1. The Open Source Way
2. Introduction
3. Communities of Practice
4. Data and references
5. Appendix
6. Dashboard

[Karsten Wade]

On Fri, Aug 06, 2010 at 03:49:24PM -0700, tosw_mail.neophyte_rep(a)ordinaryamerican.net
wrote:
>  In light of the 1956 research paper of George A. Miller of Harvard
>  University, "The Magical Number Seven, Plus or Minus Two: Some Limits
>  on our Capacity for Processing Information"
>  <http://psychclassics.yorku.ca/Miller/>;, I would like to suggest a
>  different organization of the Tale of Contents of "The Open Source
>  Way": 
That sounds like good thinking.  Honestly, I was just throwing
chapters out there without counting how long things got.

One idea that has been out there is to turn each major sub-section in
to a stand-alone page.  It makes for easier reference of these
components.

We then stitch them together in to chapters using MediaWiki
transclusions.  The table of contents is also constructed
independently.

Some specific comments inline:

>  1. The Open Source Way: Creating and nurturing communities of
>  contributors -- Main wiki page
>  2. Introduction -- What this book is, what it is not, essential
>  terminology (definitions and pointers)
>  3. Communities of practice -- The science behind the open source way 
I like this as a top-level chapter, but it could also be subbed
under the [[Introduction]]. Just something else to think about.

>      3.1 What is a Community of Practice?
>      3.2 Elements of the Community of Practice
>      3.3 Principles for Cultivating Communities of Practice
>      3.4 How to loosely organize a community -- Structure of a
>  sustainable community
>      3.5 What your organization does:
>            3.5.1 Right when practicing the open source way -- Distilled
>  "Right Way"
>            3.5.2 Wrong when practicing the open source way -- Distilled
>  "Wrong Way"
>      3.6 Business the open source way -- Applying the open source way to business 
This is interesting, tucking the chapter on applying the principles to
specific domains underneath the communities of practice chapter.  I
hadn't seen that connection before, but it does make sense.

Then we could add ongoing domain-specific chapters, as suggested here:

https://www.theopensourceway.org/wiki/Chapter_writing_methodology

>      3.7 Who else to watch -- People in the wider world who write,
>  talk, and lead community-oriented discussions and actions
>  4. Data and references -- Data and references that support the book
>      4.1 Books you should read -- Online and offline resources
>      4.2 Stuff everyone knows and forgets anyway -- Common knowledge,
>  common mistakes, common recoveries
>      4.3 Great stories to tell -- Stories that illustrate the open source way
>      4.4 How to tell if a FLOSS project is doomed to FAIL - A system
>  for evaluating the potential of an open source project
>  5. Appendix -- What fits not elsewhere but only here
>  6. Community Architecture dashboard -- Overview of this effort with pointers 
This chapter may be just cruft, leftovers from an earlier version.  We
can likely drop it.

>  And, perhaps the chapter titles could be more succinct:
>  1. The Open Source Way
>  2. Introduction
>  3. Communities of Practice
>  4. Data and references
>  5. Appendix
>  6. Dashboard 
OK, that would work.  I guess I have a tendency to like words over
not, but I agree this is supposed to be a bit more succinct of a
work.

Are you thinking of renaming the wiki pages, or just revealing them
with shorter titles in the table of contents?

thx - Karsten
-- 
name:  Karsten 'quaid' Wade, Sr. Community Gardener
team:                Red Hat Community Architecture 
uri:               http://TheOpenSourceWay.org/wiki
gpg:                                       AD0E0C41

On Sun, Aug 8, 2010 at 11:41 AM, Karsten Wade - kwade(a)redhat.com wrote:
>  On Fri, Aug 06, 2010 at 03:49:24PM -0700,
> tosw_mail.neophyte_rep(a)ordinaryamerican.net wrote:
> > In light of the 1956 research paper of George A. Miller of Harvard
> > University, "The Magical Number Seven, Plus or Minus Two: Some Limits
> > on our Capacity for Processing Information"
> > <http://psychclassics.yorku.ca/Miller/>;, I would like to suggest a
> > different organization of the Tale of Contents of "The Open Source
> > Way":
>
>  That sounds like good thinking.  Honestly, I was just throwing
>  chapters out there without counting how long things got. 
I was trained in a era where you wrote an outline of your thoughts
before you started laying down a bunch of verbiage.  This assures you
cover the information sufficiently and succinctly while providing the
reader a logical route through the information.  While most wikis are
just repositories of random information, I understood this one, at
least in part, represented a orderly statement of a single subject.

>  One idea that has been out there is to turn each major sub-section in
>  to a stand-alone page.  It makes for easier reference of these
>  components.
>
>  We then stitch them together in to chapters using MediaWiki
>  transclusions.  The table of contents is also constructed
>  independently.
>
>  Some specific comments inline:
>
> > 1. The Open Source Way: Creating and nurturing communities of
> > contributors -- Main wiki page
> > 2. Introduction -- What this book is, what it is not, essential
> > terminology (definitions and pointers)
> > 3. Communities of practice -- The science behind the open source way
>
>  I like this as a top-level chapter, but it could also be subbed
>  under the [[Introduction]]. Just something else to think about.
>  
The [[Introduction]] can be similar to an Executive Summary.  It
should reference the ideas to be explained, but should not include all
the details.

If you look closely at Chapter 3., in my Table of Contents, it has
acquired all the important content of "The Open Source Way".  I'm
worried that is too inclusive or maybe TOSW doesn't contain all the
relevant information.

> >     3.1 What is a Community of Practice?
> >     3.2 Elements of the Community of Practice
> >     3.3 Principles for Cultivating Communities of Practice
> >     3.4 How to loosely organize a community -- Structure of a
> > sustainable community
> >     3.5 What your organization does:
> >           3.5.1 Right when practicing the open source way -- Distilled
> > "Right Way"
> >           3.5.2 Wrong when practicing the open source way -- Distilled
> > "Wrong Way"
> >     3.6 Business the open source way -- Applying the open source way to business
>
>  This is interesting, tucking the chapter on applying the principles to
>  specific domains underneath the communities of practice chapter.  I
>  hadn't seen that connection before, but it does make sense.
>
>  Then we could add ongoing domain-specific chapters, as suggested here:
>
>  https://www.theopensourceway.org/wiki/Chapter_writing_methodology
>
> >     3.7 Who else to watch -- People in the wider world who write,
> > talk, and lead community-oriented discussions and actions
> > 4. Data and references -- Data and references that support the book
> >     4.1 Books you should read -- Online and offline resources
> >     4.2 Stuff everyone knows and forgets anyway -- Common knowledge,
> > common mistakes, common recoveries
> >     4.3 Great stories to tell -- Stories that illustrate the open source way
> >     4.4 How to tell if a FLOSS project is doomed to FAIL - A system
> > for evaluating the potential of an open source project
> > 5. Appendix -- What fits not elsewhere but only here
> > 6. Community Architecture dashboard -- Overview of this effort with pointers
>
>  This chapter may be just cruft, leftovers from an earlier version.  We
>  can likely drop it. 
Is it an example of proper operational monitoring of an Open Source
project?  If so, can we identify others?

> > And, perhaps the chapter titles could be more succinct:
> > 1. The Open Source Way
> > 2. Introduction
> > 3. Communities of Practice
> > 4. Data and references
> > 5. Appendix
> > 6. Dashboard
>
>  OK, that would work.  I guess I have a tendency to like words over
>  not, but I agree this is supposed to be a bit more succinct of a
>  work.
>
>  Are you thinking of renaming the wiki pages, or just revealing them
>  with shorter titles in the table of contents?
>  
I would use the shorter titles as the wiki page names.  That saves
typing in the long run and allows easier creativity in including them
in reference links within sentences, especially from outside the wiki.

>  thx - Karsten

[Karsten Wade]

OK, I'd like us to make these changes, they seem like a good move
forward.  I'll make some comments below.

Do you feel comfortable with how we can do this with the wiki?

We can construct the new table of contents on the [[Main_page]], and
then sub-tables in the chapter pages.  This keeps the wiki pages from
being too long.  For example, on the [[Communities of Practice]] page
is a hand-created table of contents that points at a series of
stand-alone pages.

How stand-alone?  I would think having the first nested section,
e.g. "3.6 Business the open source way -- Applying the open source way
to business", would be a stand-alone page.  (It's there, btw,
[[Business the open source way]] exists with that simple page title
pattern.)

I did a small bit of clean-up on the [[Main_page]], and I am thinking
about moving the contribution section to a stand-alone page and having
just a small few sentences on the main page about contribution with a
link out.

More comments below:

On Mon, Aug 09, 2010 at 07:19:34AM -0700, tosw_mail.neophyte_rep(a)ordinaryamerican.net
wrote:
>  On Sun, Aug 8, 2010 at 11:41 AM, Karsten Wade - kwade(a)redhat.com
> wrote:
>  
>  I was trained in a era where you wrote an outline of your thoughts
>  before you started laying down a bunch of verbiage.  This assures you
>  cover the information sufficiently and succinctly while providing the
>  reader a logical route through the information.  While most wikis are
>  just repositories of random information, I understood this one, at
>  least in part, represented a orderly statement of a single subject. 
I definitely don't disagree with that methodology, I'm a formally
trained writer myself.  I've also learned, accepted, and embraced the
value gained some of these other, more chaotic writing methods.
Community documentation is harder to outline, it sprouts new arms and
heads just as you think you have it all figured out.  The table of
contents is one place where we bring some order from the chaos.

>  > One idea that has been out there is to turn each major
> sub-section in
>  > to a stand-alone page.  It makes for easier reference of these
>  > components.
>  >
>  > We then stitch them together in to chapters using MediaWiki
>  > transclusions.  The table of contents is also constructed
>  > independently.
>  >
>  > Some specific comments inline:
>  >
>  >> 1. The Open Source Way: Creating and nurturing communities of
>  >> contributors -- Main wiki page
>  >> 2. Introduction -- What this book is, what it is not, essential
>  >> terminology (definitions and pointers)
>  >> 3. Communities of practice -- The science behind the open source way
>  >
>  > I like this as a top-level chapter, but it could also be subbed
>  > under the [[Introduction]]. Just something else to think about.
>  >
>  
>  The [[Introduction]] can be similar to an Executive Summary.  It
>  should reference the ideas to be explained, but should not include all
>  the details. 
I understand, it became more clear how the new Chapter 3. worked, the
more I thought about it.

>  If you look closely at Chapter 3., in my Table of Contents, it has
>  acquired all the important content of "The Open Source Way".  I'm
>  worried that is too inclusive or maybe TOSW doesn't contain all the
>  relevant information. 
I'm going back to basics in my mind, which is PIE - Principle,
Implementation, Example.

If we make a single checklist that names each principle (linked to the
appropriate page), and put that at the end of the [[Introduction]],
then we have a single chapter that gives an overview of the
principles.

Then Chapter 3. is mostly about implementation, but it also defines
principles as they are applied to specific domains.

Finally, [[Data and references]] contains the examples, the stories
that tell what happened when a what and a how were put to practice.  I
wouldn't mind if we called it something more descriptive, too.

>  > This chapter may be just cruft, leftovers from an earlier
> version.  We
>  > can likely drop it.
>  
>  Is it an example of proper operational monitoring of an Open Source
>  project?  If so, can we identify others? 
We don't have an operational monitoring in place that can inform a
chapter; there are others, but I don't know who has anything any good.
What to track and the relevance are under discussion in the wider
communities.  Let's take this out until there is something more there,
unless we get the time to do more research on other worthwhile
dashboard projects.

>  I would use the shorter titles as the wiki page names.  That saves
>  typing in the long run and allows easier creativity in including them
>  in reference links within sentences, especially from outside the wiki. 
Well, they are descriptive enough, so that's OK.  I guess it's also
really time to refactor the longer pages in to stand-alone
sub-sections.

- Karsten
-- 
name:  Karsten 'quaid' Wade, Sr. Community Gardener
team:                Red Hat Community Architecture 
uri:               http://TheOpenSourceWay.org/wiki
gpg:                                       AD0E0C41