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