[FM Discuss] Quick impressions following CiviCRM book sprint

[Andy Oram]

I had a lot of fun working on this sprint, even though I was
disadvantaged by being off-site and even though I couldn't put in time
at all the moments when I would have been helpful (more on that in a
moment).

I'm sure we'll all have insights after we evaluate the book that Adam
and crew are polishing off over the next few hours. But because I've
finished my part of the sprint (I'll certainly be back to review and
edit the draft later), I'll put out a few ideas while they're fresh.

These ideas concern my role as ueber-reviewer and professional editor.
I can't judge many other things because I wasn't in the room with
everybody.

I heartily endorse the sprint model. I've never seen a group of
authors be so productive as they routinely are during sprints. I want
to figure out how to maximize my effectiveness within this structure.


Outline and team spirit
-----------------------

These areas are where I think this is where I've been most helpful so
far. This is because experienced sprinters hammered home to me that a
strong outline is crucial to a successful sprint. Ironically, though,
it wasn't ultimately I who designed the outline.

The CiviCRM folks needed coordination. They have tremendous experience
and lots of ideas of what's missing from the documentation. Their
suggestions were deep: how to prepare your organization, how to map
your current practice onto CiviCRM, etc. But there was too much
centrifugal force during early discussions; nothing was coalescing.

I'm pretty proud of how I handled the surfeit of creativity. I just
kept them talking, told them to write down ideas, and tried to
formalize what they wrote so it looked actionable.

Eventually I realized we should have a vision statement. This might
sound like overkill for a sprint, but I think it's useful for every
endeavor. We didn't really work on it, but I threw out ideas I'd heard
and established a sense of a mission. I think this little digression
came at a good time, after I had heard a lot of individual visions and
could sense a direction. (That didn't help us later when we needed
it--see next section.)

The reason I used the title "Outline and team spirit" together,
instead of breaking them up, is that the two endeavors went
hand-in-hand. The sense of "we're cookin'" and "we can do it" came
with work on the outline, and that spirit probably carried the sprint
forward.

So about three days before the sprint--man, did we ever have outline.
In spades. I was not experienced enough to say, "Let's trim this," but
Adam recognized the need right away. We agree that it's good to
solicit lots of ideas. You can't turn on a spigot in the community and
then try to throttle it. But somebody had to choose the actual topics
to cover. That story comes next.


Stakeholders
------------

Having realized that the outline had to be trimmed. Adam ran into
trouble. His assessment, which sounds reasonable to me, is that the
people working on the outline--and particularly the group who had a
long conference call with me two weeks before the sprint--were
substantially different from those who came to the sprint. The overlap
consisted of just three people, I think. (Adam, feel free to correct
any of my impressions.)

Worse still, I had been intensively involved in discussions around
scope and outline, but Adam had been more on the sidelines. Adam
selected some topics that made up a coherent scope, but it was
vehemently rejected by the sprint participants. I had signed off on
Adam's selection, but clearly there were too many different,
non-synaptic points of view. It's nobody's fault.

Luckily, the sprint team quickly picked out an outline, so we got over
that mini-crisis.


Sprint-week editing
-------------------

I don't know what happened among the team except that I saw people log
in early and stay late, but they were certainly productive. Like all
sprints, the level of professionalism in the actual writing varies,
but the ideas are almost 100% on target (and the things that were
inappropriate for the book got weeded out). I'll concentrate again on
my role.
 
I jumped in quite early and edited a few chapters to try to set a tone
and a level of expectation. (Mostly: "does the audience need this?"
and "what's missing?") I think this was successful. When I came back
to those chapters, people had naturally added a lot more text--but I
think the focus and organization were also better. Of course, they
might have reached that point without me too.

But then I fell behind. This was inevitable because I was still trying
to do most of my day job and lead a life. So for a couple days, gobs
of new text were added without my offering much review. Because I was
offsite and had just the extremely narrow channels of email and I for
communication, I also didn't know what parts people wanted help on
most of the time. (Occasionally I would come online at a good time and
someone could point me to a chapter.)

I spent a lot of time editing, nevertheless. My log says 7 hours on
Wednesday (hard to believe), 4 on Thursday, and 3 today. I wonder
whether I could have focused my review to help set the direction
more. I don't know whether I should have reviewed different material,
or offered a different kind of review.

My review did make a difference. But looking over the draft today, I
realized I could have done more. By this time it was too late to
recommend new sections or a big reorganization (although we can do
that later). Among the things I found too late to fix were:

* A large section named "Constituents and Relationships," with five
  rich chapters, that jumps suddenly into a new level of detail with
  no intro. We need a little section saying "Here's where we got to,
  here's where we're going."

* Two parts of different chapters that cover different but closely
  related topics about the architecture and software pieces needed for
  CiviCRM. I recommended they be blended, a subtle task.

* A long chapter with two parts that I suspect are related in some way
  that's not clear. If they're closely related, they need to be tied
  together. Otherwise they should be two separate chapters.

I suspect (and I think Adam will back my up) that at a sprint
pace--half a dozen people intensively writing--no single editor can
keep a book on track. The sprint participants kept it mostly on track
by talking with Adam and each other.


Edits and overlays
------------------

I'm an aggressive editor. When something doesn't flow right, I have no
scruples about breaking it into pieces, writing new parts, and making
a completely new chapter out of it. I do this even when I understand
the material imperfectly, knowing it will come out with errors.

I need to edit this way because the perfect flow isn't clear to me at
the start. I have to work the clay, metaphorically speaking, to find
the solution. As each part comes out looking right, I can proceed to
the next or return to a part I edited before.

On other projects I've worked on, this process works fine. The author
simply fixes the errors. My general structure is usually good, or is
easy to rearrange.

One person on the sprint freaked out a bit at this approach. Adam told
me not to take him seriously, but I think his concerns were
reasonable. Time was tight and he didn't want to spend time on someone
else's mistakes.

Now, I could have been a sophist and explained that I was not
introducing errors. Rather, the errors were implicitly in the text
already--because it was ambiguous, because it juxtaposed things that
were not meant to go together, because it somehow leaves an impression
the author doesn't mean to leave. But I didn't try to defend my
work. I made copies of test and inserted my ideas as comments without
changing the original (except for copy-editing). This worked fine.

Andy