[TOS] textbook roadmap by OSCON (was: Scribd)

Matthew Jadud mjadud at allegheny.edu
Tue Jun 29 02:36:51 UTC 2010


Hi Karsten,

2010/6/28 Karsten Wade <kwade at redhat.com>:
> topics is talking about the future of the textbook.  In fact, I

I have three concerns that I've been trying to figure out how to
voice. One involves more clearly defining the readership, the second
the process by which work is acknowledged, and third is the
toolchain/editing/commit process. Like all opinions/thoughts, they are
freely given and may be freely disregarded.

While I only had time during the sprint to make it through the first
few chapters, I found myself rewriting a fair bit -- mostly, expanding
material out to the level that I thought was necessary to make the
book usable to the kinds of students I teach. (I think the book is
very terse in most places, and often assumes too much in terms of the
reader's knowledge and/or interest.) That said, it might be that I
teach students who are different from those at other institutions...
and therefore, my assumptions about the reader are not in keeping with
the assumptions of the original authors. Regardless, my question is:
"who is the reader?" Could we have one or two personas developed by
the current authorship team that make clear what kind of readers are
being targeted?

The second point is that there isn't, as far as I remember, even an
acknowledgments section in the current book. (If I'm wrong, it's
because I don't remember, and didn't check right now. My bad.) I'm not
necessarily angling for attribution per se, but most open (code)
projects do better than the book is currently. That is, if I
contribute enough code, I get to add my name to the (C) list on the
source file, or to the list of contributors, or something. If you're
not going to do that, proclaim it. If you are going to have a
contributors page, make clear what "counts." If you're willing to grow
the authorship list, decide amongst the current authors what level of
contribution is necessary for that to occur. Again, it doesn't
particularly matter to me what you decide amongst the current authors,
but decide it and make it clear to other potential contributors.

Lastly, I would prefer a toolchain that was less heavyweight while the
book was in development. The most common writing tools for CS faculty
are probably LaTeX and/or Word/OO. Publican looked like a beast, and
seems to involve pulling data from the (live) wiki. (Again, I'm
potentially way off here...) As far as I can tell, I cannot write and
see what my writing looks like in a formatted version without editing
the "live" source. If that is the case, it's a barrier... because I
can't edit without modifying the "live" book. I can't
experiment/explore and then submit a "patch." As a result, even if my
first two concerns were addressed, I'd be very nervous  about
contributing, simply because there is no way to evaluate (as a
community) and discuss any changes I might make... the changes are
simply live, or they're rolled back. That means my contributions have
a high cost, and I have no way of keeping my own "local changes" even
if the community decides to discard them. In short, I think the wiki
lacks the fundamental features of a VCS that are essential for any
collaborative project, especially a book.

Mind you, my summer is spoken for through OSCON, so I'm offering these
comments from the perspective of "if I wasn't busy getting my own code
and documentation ready for OSCON, these are the kinds of concerns I'd
have." At the end of the day, I'm inclined to agree (as has been said
by one or two others here) that the person driving and contributing
the most has the most vested interest in the tools and process... so
please take these as kindly offered perspectives from someone who is
not, in all likelihood, going to be making any contributions in the
next month.

Cheers,
Matt



More information about the tos mailing list