[TOS] textbook 0.8.1

[Karsten Wade]

On Tue, Aug 17, 2010 at 02:42:10PM -0700, tosmaillist.neophyte_rep at ordinaryamerican.net wrote:
> Comments inline:
> 
> 2010/8/17 Karsten Wade - kwade at redhat.com:
> >
> > * There are ways with wiki tools to get more of what you are looking
> >  for.
> >
> 
> Since the wiki based processes are not enforced by a tool, I feel
> there needs to be a documented set of "Rules of Engagement" so we can
> all contribute efficiently.
> 
> > * By reviewed before submission, I presume you mean "reviewed by
> >  others" not by yourself.  You can use the practice of putting change
> >  ideas in your user namespace, e.g. [[user:Jadudm/Foo_change]].  If
> >  you want a diff, you paste in the original content, save it, then
> >  make the change, save that, and the history shows a diff of the
> >  two.  Think of it like an SCM clone.
> 
> This sequence of actions (copy, paste, save, then edit) are what I'm
> talking about as part of the "Rules of Engagement".  If the
> contributor doesn't have any experience using a wiki as a Source Code
> Manager (SCM), that copy, let alone the first save is not an obvious
> requirement.

Roger that.  I took a first pass at that page (as a generic page
useful for more than just this textbook effort):

http://teachingopensource.org/index.php/Textbook_writing_rules_of_engagement

I tried to do the steps full justice and a reasonable summary.
Patches welcome, feel free to edit that page directly, or use its
steps to create a sandbox page to edit in.

> > * If we can get some progress on the tool that Ian and I dreamed on,
> >  we can get every change on a watched page captured and sent to
> >  email.  MediaWiki, by default, sends one change for a watched page,
> >  and does not send any other until you visit that page.  That's from
> >  MediaWiki culture that doesn't work as well in environments used to
> >  diff and patch review via mailing list.  Ian's tool would resolve
> >  that to make it easier to watch and review on the live page.
> >
> 
> <snip>
> 
> >
> > My concern about using any other tool than a wiki is the significant
> > increase in barriers to contribution.  I'm confident it's easier to
> > fix our concerns and usage of the wiki, let's see if we can make some
> > big improvements on the edit and writing workflow.
> >
> 
> Barriers to contribution should not be removed if chaos ensues.  There
> needs to be enough control that the neophyte does not destroy the work
> of the veterans.
> 
> Please provide supporting information for your confidence.

I get where you are coming from, I think, and in general I think the
tools themselves are enough barrier to the truly accidentally
destructive.  (Separate discussion is intentional distruction,
e.g. spam.)

Creating the lowest barriers possible and feasible (e.g., not to the
Linux kernel, but this isn't that) and allowing people to experiment,
make mistakes, learn, improve, and do all this safely (thanks to SCM
built into the wiki) is an essential part of the open source way.

My supporting information is the experience of communities I'm
involved in doing everything possible to make that happen, and the
resulting improvements.  For example, the Fedora Project.  The
principles and guidance are now all written in to a book, and some
relevant sections are:

https://www.theopensourceway.org/wiki/Stuff_everyone_knows_and_forgets_anyway#Make_sure_everyone_has_an_equal_and_clear_method_for_access_to_write-commit_to_open_tools

https://www.theopensourceway.org/wiki/Stuff_everyone_knows_and_forgets_anyway#Use_version_control_for_your_content_as_well_as_code_-_everyone_watches_the_changes

https://www.theopensourceway.org/wiki/How_to_loosely_organize_a_community#Use_lightweight.2C_open_collaboration_tools_-_wikis.2C_mailing_lists.2C_IRC.2C_version_control.2C_bug_trackers_-_and_give_out_access

https://www.theopensourceway.org/wiki/How_to_loosely_organize_a_community#Make_your_contribution_policy_clear_and_as_low_as_possible

However, I note there isn't a clear principle in that book that
covers my thesis directly, so perhaps there should be. :)

> >> Thoughts?
> >
> > We want to enable "edit as you see it written" as well as "edit in
> > batches".  I'd like to get more of the former this time so we can
> > correct each other before we get too much content plowed, watered, and
> > grown.
> >
> 
> Planting in weedy compost is counter-productive.  Let's be careful to
> properly prepare the soil.

The above process is one where you remove the weeds as you go rather
than let them build up and have a "really big weeding day."

This is why page changes should be granular and many people can (and
do) watch the changes.  If I see you do something today that I can
correct right now, I make it so you don't have to repeat that mistake
N times across the content.  That learning goes the other direction, I
might learn something that informs me on improvements in my subsequent
work that I wouldn't catch if I did a really big weeding day.

This, then, is a way that the veterans help the neophytes improve
their work as they go, which means less editing/fixing later.  It is a
little work now and as we go rathern than, in my experience, a lot
more work when bundled all together.  The latter also loses a lot of
the learning experience -- people remember and learn better when they
see the fix in real time instead of as a batch in a grade afterward.
It's part of the mentoring process as practiced the open source way.

- Karsten
-- 
name:  Karsten 'quaid' Wade, Sr. Community Gardener
team:                Red Hat Community Architecture 
uri:               http://TheOpenSourceWay.org/wiki
gpg:                                       AD0E0C41
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://teachingopensource.org/pipermail/tos/attachments/20100819/a4b3defb/attachment.asc>