On Mon, Aug 16, 2010 at 08:05:57PM -0400, Matthew Jadud wrote: > 2010/8/16 Karsten Wade <[email protected]>: > > Thoughts? > > My biggest concerns, when editing version 0.8, were that: > > 1. Each chapter clearly had a different "voice," and it was annoying > to me as a reader. At some point, it seems that someone should do a > pass through the book and unify the voice.
OK, agreed, this was a clear objective for the next version from way
back then and we can at least make some progress on this. Added it to
the to-do section on the planning page.
> 2. I felt much of the text was written in an incredibly terse style,
> which I thought left out a lot of critical detail. (More than just
> copyediting was required---I found myself expanding a single sentence
> into a paragraph just to make sure that the concept could be
> understood by a novice.)
Understood. Can we at least identify the troublesome paragraphs so we
can work on rewriting? Or is that a reading depth beyond "glance and
note the problematic ones"?
> 3. There is no clear indication that contribution/editing at this
> level is desired at this stage, nor is there any indication of what
> kind of contribution this is. (Eg. is it authorship? Editing? Is is
> something that should be acknowledged?)
Agreed, this was another good point you raised.
So, I'm adding it as a task to resolve attribution of contributors.
My goal would be to have a front page with a list of everyone, under
blocks of what they did. If a chapter has a primary author and/or
editor, I'm inclined to think that is worth special notice in the
attribution, and try to tie that to specific versions of the output.
> I remain concerned about the authoring environment -- perhaps because
> I don't understand it. With version control, you can submit patches,
> and they can be reviewed and discussed. On the wiki, there is a live
> environment that can neither be reviewed before submission nor
> "branched" in multiple directions. I'm hesitant to contribute to the
> process simply because I think a lot of the text needs
> revision/expansion/clarification, but I'm not an author. And since I
> can't "submit a patch" and discuss it with anyone, I simply have to
> edit the one live master environment, and hope that the changes are
> acceptable. While Greg had encouraged me to "be bold" during the
> sprint, I was mostly working on his chapters at the time, and I don't
> know if all the authors really feel the same way about their words
> ("hey, you completely rewrote those paragraphs!") as many people feel
> about their code ("wow! you made it 100 lines shorter and 3x as
> fast!").
I'm going to go read the rest of this thread, then I might come back
here with more on this topic. Just some general points:
* There are ways with wiki tools to get more of what you are looking
for.
* 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.
* 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.
> It might be that the kinds of contributions I feel I could make to the
> book (like the edits I was making during the sprint) are problematic
> (for the reasons stated).
Not sure about that. FWIW, I'm used to being a more direct editor,
making changes and writing in the summary field why. But, yes, that
is more wiki culture than academic writing culture.
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.
> 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.
> I have other writing I should be doing at this stage, and classes
> start in a week... but these were the concerns I had when I was
> working on the book before, and they're the concerns I still have, so
> I thought I'd share them, and hope someone can set me straight/clarify
> any confusion I might have.
Excellent material, thanks.
- Karsten
--
name: Karsten 'quaid' Wade, Sr. Community Gardener
team: Red Hat Community Architecture
uri: http://TheOpenSourceWay.org/wiki
gpg: AD0E0C41
pgproTq327rdp.pgp
Description: PGP signature
_______________________________________________ tos mailing list [email protected] http://teachingopensource.org/mailman/listinfo/tos
